The Caching Proxy API
This section discusses the Caching Proxy application programming interface (API):
what it is, why it is useful, and how it works.
IMPORTANT: Caching Proxy is available on all Edge component installations, with the following exceptions:
- Caching Proxy is not available for Edge component installations that run on Itanium 2 or AMD Opteron 64-bit processors.
- Caching Proxy is not available for Edge component installations of Load Balancer for IPv4 and IPv6.
Overview of the Caching Proxy API
The API is an interface to the Caching Proxy that enables you to extend the proxy server's
base functions. You can write extensions, or plug-ins, to do customized processing,
including the following examples:
- Enhancing the basic authentication routine, or replacing it with a site-specific
process.
- Adding error-handling routines to track problems or alert for serious
conditions.
- Detecting and tracking information that comes in from the requesting client,
such as server referrals and user agent codes.
The Caching Proxy API provides the following benefits:
- Efficiency
- The API is designed specifically for the threaded processing system used
by the Caching Proxy.
- Flexibility
- The API contains rich and versatile functions.
- The API is platform independent and language neutral. It runs on all Caching Proxy platforms,
and plug-in applications can be written in most of the programming languages
supported by these platforms.
- Ease of use
- Simple data types are passed by reference instead of by value (for example,
long *, char *).
- Each function has a fixed number of parameters.
- Includes bindings for the C language.
- Plug-ins do not impact allocated memory; plug-in applications allocate
and free memory independently of other Caching Proxy processes.
General procedure for writing API programs
Before writing your Caching Proxy plug-in programs, you
need to understand how the proxy server works. The behavior of the proxy server can
be divided into several distinct processing steps. For each of these steps,
you can supply your own customized functions using the API. For example, do
you want to do something after a client request is read but before performing
any other processing? Or maybe you want to perform special routines during
authentication and then again after the requested file is sent.
A library of predefined functions is provided with the API. Your plug-in
programs can call the predefined API functions in order to interact with the proxy server process
(for example, to manipulate requests, to read or write request headers, or
to write to the proxy server's logs). These functions should not be confused with
the plug-in functions that you write, which are called by the proxy server. The
predefined functions are described in Predefined functions and macros.
You instruct the proxy server to call your plug-in functions at the appropriate
steps by using the corresponding Caching Proxy API directives in your server configuration
file. These directives are described in Caching Proxy configuration directives for API steps.
This document includes the following:
You can use these components and procedures to write your own Caching Proxy plug-in
programs.
Server process steps
The basic operation of the proxy server can be
broken up into steps based on the type of processing that the server performs
during that phase. Each step includes a juncture at which a specified part
of your program can run. By adding API directives to your Caching Proxy configuration
file (ibmproxy.conf), you indicate which of your plug-in functions you want
to be called during a particular step. You can call several plug-in functions
during a particular process step by including more than one directive for
that step.
Some steps are part of the server request process. In other words, the proxy server executes
these steps each time it processes a request. Other steps are performed independently
of request processing; that is, the server executes these steps regardless
of whether a request is being processed.
Your compiled program resides in a shared object, for example, a DLL or
.so file, depending on your operating system. As the server proceeds through
its request process steps, it calls the plug-in functions associated with
each step until one of the functions indicates that it has handled the request.
If you specify more than one plug-in function for a particular step, the functions
are called in the order in which their directives appear in the configuration
file.
If the request is not handled by a plug-in function (either you did not
include a Caching Proxy API directive for that step, or your plug-in function for that
step returned HTTP_NOACTION), the server performs its default action for that
step.
Note: This is true for all steps except the Service
step; the Service step does not have a default action.
Figure 1 depicts the steps of the proxy server process and defines
the processing order for the steps that are related to request processing.
Four of the steps on the diagram are executed independently from the
processing of any client request. These steps are related to the running and
maintenance of the proxy server. They include the following:
- Server Initialization
- Midnight
- GC Advisor
- Server Termination
The following list explains the purpose of each step pictured in Figure 1. Note that not all steps are guaranteed to be called for
a particular request.
- Server Initialization
- Performs initialization when the proxy server is started and
before any client requests are accepted.
- Midnight
- Runs a plug-in at midnight, with no request context. This step is shown
separately in the diagram because it is not part of the request process; in
other words, its execution is independent of any request.
- GC Advisor
- Influences garbage collection decisions for files in the cache. This
step is shown separately in the diagram because it is not part of the request
process; in other words, its execution is independent of any request. Garbage
collection is done when the cache size reaches the maximum value. (Information
about configuring cache garbage collection is included in the WebSphere® Application Server Caching Proxy Administration Guide.)
- PreExit
-
Performs processing after a request is read but before anything else
is done.
If this step returns an indication that the request was processed
(HTTP_OK), the server bypasses the other steps in the request process and
performs only the Transmogrifier, Log, and PostExit steps.
- Name Translation
- Translates the virtual path (from a URL) to the physical path.
- Authorization
-
Uses stored security tokens to check the physical path for protections,
ACLs, and other access controls, and generates the WWW-Authenticate headers
required for basic authentication. If you write your own plug-in function
to replace this step, you must generate these headers yourself.
See Authentication and authorization for more information.
- Authentication
-
Decodes, verifies, and stores security tokens.
See Authentication and authorization for
more information.
- Object Type
- Locates the file system object indicated by the path.
- Post Authorization
-
Performs processing after authorization and object location but before
the request is satisfied.
If this step returns an indication that
the request was processed (HTTP_OK), the server bypasses the other steps in
the request process and performs only the Transmogrifier, Log, and PostExit
steps.
- Service
- Satisfies the request (by sending the file, running the CGI, etc.)
- Proxy Advisor
- Influences proxy and caching decisions.
- Transmogrifier
- Gives write access to the data portion of the response sent to the client.
- Log
- Enables customized transaction logging.
- Error
- Enables customized responses to error conditions.
- PostExit
- Cleans up resources allocated for request processing.
- Server Termination
- Performs clean-up processing when an orderly shutdown occurs.
Guidelines
- Write your program, following the syntax and guidelines provided for the
server's plug-in functions. Give each of your plug-in functions a unique function
name and call the server's predefined functions as needed.
On AIX® systems, you
need an export file (for example, libmyapp.exp) that lists your plug-in functions,
and you must link with the Caching Proxy API import file, libhttpdapi.exp.
On Linux, HP-UX, and Solaris systems, you must link with the libhttpdapi and
libc libraries.
On Windows® systems, you need a module definition
file (.def) that lists your plug-in functions, and you must link with HTTPDAPI.LIB.
Be sure to include HTAPI.h and to use the HTTPD_LINKAGE macro in your
function definitions. This macro ensures that all the functions use the same
calling conventions.
- The server runs in a multithreaded environment; therefore, your plug-ins
must be thread safe. If your application is reentrant, performance does not
decrease.
- Keep the actions in your plug-ins to a thread scope. Do not perform any
actions at a process scope, for example, exiting, changing the user ID, or
registering a signal handler.
- Do not use global variables, or, if you must use them, protect global
variables with a mutual exclusion semaphore.
- Remember to set the Content-Type header if you are using the HTTPD_write()
function to send data back to the client.
- Always check return codes and provide conditional processing where necessary.
- Compile and link your program, referring to the documentation for your
compiler to build a shared object (for example, a DLL or .so file) as required
for your operating system.
Use the following compile and link commands
as a guideline.
- AIX, using IBM® CSet++
- Compile:
cc_r -c -qdbxextra -qcpluscmt foo.c
- Link:
cc_r -bM:SRE -bnoentry -o libfoo.so foo.o -bI:libhttpdapi.exp
-bE:foo.exp
(This command is shown on two lines for readability
only.)
- HP-UX, using HP C/ANSI C Developer's Bundle
and HP aC++ Compiler
- Linux, using the Gnu Compiler C (GCC) Version 3.2.X
- Solaris, using Sun Workshop
- Windows, using Microsoft® Visual
C++
To specify exports, use one of these methods:
- Add _declspec(dllexport) definitions in the source.
- Specify /EXPORT:entryname on the LIB command line.
- Create a module definition file with an EXPORTS statement.
- Add Caching Proxy API directives to your configuration file to associate your program's
plug-in functions with the appropriate steps. There is a separate directive
for each step in the server request process. Stop and restart your server
to make the new directives take effect.
Note:
The Caching Proxy does not
unload shared objects (DLL or .so files) even at restart. You must stop and
then start the server in order to release shared objects.
- Test your program rigorously before using it in a production environment.
Because the Caching Proxy is a threaded server, you must apply more rigorous testing
than is necessary for a forking server. Errors in your program can cause the
proxy server to fail because the proxy server calls your program directly,
and they both run in the same process space.
Plug-in functions
Follow the syntax presented in Plug-in function prototypes to write your
own program functions for the defined request processing steps.
Each of your functions must fill in the return code parameter with a value
that indicates what action was taken:
- The code HTTP_NOACTION (value 0) means that no relevant action
was taken. If this code is returned, the proxy server takes its default action
for this step.
- One of the valid HTTP return codes indicates that the plug-in function
handled the step. (See HTTP return codes and values for a list of valid
return codes.) If a valid HTTP return code is given, no other plug-in functions
are called to handle that step of this request.
Plug-in function prototypes
The function prototypes for each Caching Proxy step show the format to use and explain
the type of processing they can perform. Note that the function names are
not predefined. You must give your functions unique names, and you can choose
your own naming conventions. For ease of association, this document uses names
that relate to the server's processing steps.
In each of these plug-in functions, certain predefined API functions are
valid. Some predefined functions are not valid for all steps. The following
predefined API functions are valid when called from all of these plug-in functions:
- HTTPD_set
- HTTPD_extract
- httpd_setvar
- httpd_getvar
- HTTPD_log* functions
Additional valid or invalid API functions are noted in the function prototype
descriptions.
The value of the handle parameter sent to
your functions can be passed as the first argument to the predefined functions.
Predefined API functions are described in Predefined functions and macros.
- Server Initialization
-
void HTTPD_LINKAGE ServerInitFunction (
unsigned char *handle,
unsigned long *major_version,
unsigned long *minor_version,
long *return_code
)
A function defined for this step is called once when your module is
loaded during server initialization. It is your opportunity to perform initialization
before any requests have been accepted.
Although all server initialization
functions are called, a error return code from a function in this step causes
the server to ignore all other functions configured in the same module as
the function that returned the error code. (That is, any other functions contained
in the same shared object as the function that returned the error are not
called.)
The version parameters contain the proxy server's version number;
these are supplied by the Caching Proxy.
- PreExit
-
void HTTPD_LINKAGE PreExitFunction (
unsigned char *handle,
long *return_code
)
A function defined for this step is called for each
request after the request has been read but before any processing has occurred.
A plug-in at this step can be used to access the client's request before it
is processed by the Caching Proxy.
Valid return codes for the preExit function
are the following:
- 0 (HTTP_NOACTION)
- 200 (HTTP_OK)
- HTTP errors in the 4xx or 5xx series (for example, 404,
HTTP_NOT_FOUND)
Other return codes must not be used.
If this function returns
HTTP_OK, the proxy server assumes that the request has been handled. All subsequent
request processing steps are bypassed, and only the response steps (Transmogrifier,
Log, and PostExit) are performed.
All predefined API functions are valid
during this step.
- Midnight
-
void HTTPD_LINKAGE MidnightFunction (
unsigned char *handle,
long *return_code
)
A function defined for this step runs daily at midnight
and contains no request context. For example, it can be used to invoke a child
process to analyze logs. (Note that extensive processing during this step
can interfere with logging.)
- Authentication
-
void HTTPD_LINKAGE AuthenticationFunction (
unsigned char *handle,
long *return_code
)
A function defined for this step is called for each
request based on the request's authentication scheme. This function can be
used to customize verification of the security tokens that are sent with a
request.
- Name Translation
-
void HTTPD_LINKAGE NameTransFunction (
unsigned char *handle,
long *return_code
)
A function defined for this step is called for each
request. A URL template can be specified in the configuration file directive
if you want the plug-in function to be called only for requests that match
the template. The Name Translation step occurs before the request is processed
and provides a mechanism for mapping URLs to objects such as file names.
- Authorization
-
void HTTPD_LINKAGE AuthorizationFunction (
unsigned char *handle,
long *return_code
)
A function defined for this step is called for each
request. A URL template can be specified in the configuration file directive
if you want the plug-in function to be called only for requests that match
the template. The Authorization step occurs before the request is processed
and can be used to verify that the identified object can be returned to the
client. If you are doing basic authentication, you must generate the required
WWW-Authenticate headers.
- Object Type
-
void HTTPD_LINKAGE ObjTypeFunction (
unsigned char *handle,
long *return_code
)
A function defined for this step is called for each request.
A URL template can be specified in the configuration file directive if you
want the plug-in function to be called only for requests that match the template.
The Object Type step occurs before the request is processed and can be used
to check whether the object exists, and to perform object typing.
- PostAuthorization
-
void HTTPD_LINKAGE PostAuthFunction (
unsigned char *handle,
long *return_code
)
A function defined for this step is called after the
request has been authorized but before any processing has occurred. If this
function returns HTTP_OK, the proxy server assumes that the request has been handled.
All subsequent request steps are bypassed, and only the response steps (Transmogrifier,
Log, and PostExit) are performed.
All server predefined functions are
valid during this step.
- Service
-
void HTTPD_LINKAGE ServiceFunction (
unsigned char *handle,
long *return_code
)
A function defined for this step is called for each
request. A URL template can be specified in the configuration file directive
if you want the plug-in function to be called only for requests that match
the template. The Service step satisfies the request, if it was not satisfied
in the PreExit or PostAuthorization steps.
All server predefined functions
are valid during this step.
Refer
to the Enable directive in the WebSphere Application Server Caching Proxy Administration Guide for information on configuring your
Service function to be executed based on the HTTP method rather than on the
URL.
- Transmogrifier
- The functions called in this process step can be used to filter response
data as a stream. Four plug-in functions for this step are called in sequence,
and each acts as a segment of pipe through which the data flows. That is,
the open, write, close, and error functions
that you provide are called, in that order, for each response. Each function
processes the same data stream, in turn.
For this step, you must implement
the following four functions. (Your function names do not need to match these
names.)
- Open
void * HTTPD_LINKAGE openFunction (
unsigned char *handle,
long *return_code
)
The open function performs any initialization (such as
buffer allocation) required to process the data for this stream. Any return
code other than HTTP_OK causes this filter to abort (the write and close functions
are not called). Your function can return a void pointer so that you can allocate
space for a structure and have the pointer passed back to you in the correlator parameter of the subsequent functions.
- Write
void HTTPD_LINKAGE writeFunction (
unsigned char *handle,
unsigned char *data, /* response data sent by the
origin server */
unsigned long *length, /* length of response data */
void *correlator, /* pointer returned by the
'open' function */
long *return_code
)
The write function processes the data and can call the
server's predefined HTTPD_write() function with the new or changed data. The
plug-in must not attempt to free the buffer passed to it or expect the server
to free the buffer it receives.
If you decide not to change the data
during the scope of your write function, you still must call the HTTPD_write()
function during the scope of either your open, write, or close function in
order to pass the data for the response to the client. The correlator argument is the pointer to the data buffer that was returned in your open routine.
- Close
void HTTPD_LINKAGE closeFunction (
unsigned char *handle,
void *correlator,
long *return_code
)
The close function performs any clean-up actions (such
as flushing and freeing the correlator buffer) required to complete processing
the data for this stream. The correlator argument is the pointer
to the data buffer that was returned in your open routine.
- Error
void HTTPD_LINKAGE errorFunction (
unsigned char *handle,
void *correlator,
long *return_code
)
The error function enables performance of clean-up actions,
such as flushing or freeing the buffered data (or both) before an error page
is sent. At this point, your open, write, and close functions are called to
process the error page. The correlator argument is the pointer to
the data buffer that was returned in your open routine.
Notes:
- GC Advisor
-
void HTTPD_LINKAGE GCAdvisorFunction (
unsigned char *handle,
long *return_code
)
A function defined for this step is called for each
file in the cache during garbage collection. This function enables you to
influence which files are kept and which files are discarded. For more information,
see the GC_* variables.
- Proxy Advisor
-
void HTTPD_LINKAGE ProxyAdvisorFunction (
unsigned char *handle,
long *return_code
)
A function defined for this step is invoked during
service of each proxy request. For example, it can be used to set the USE_PROXY
variable.
- Log
-
void HTTPD_LINKAGE LogFunction (
unsigned char *handle,
long *return_code
)
A function defined for this step is called for each
request after the request has been processed and the communication to the
client has been closed. A URL template can be specified in the configuration
file directive if you want the plug-in function to be called only for requests
that match the template. This function is called regardless of the success
or failure of the request processing. If you do not want your log plug-in
to override the default log mechanism, set your return code to HTTP_NOACTION
instead of HTTP_OK.
- Error
-
void HTTPD_LINKAGE ErrorFunction (
unsigned char *handle,
long *return_code
)
A function defined for this step is called for each
request that fails. A URL template can be specified in the configuration file
directive if you want the plug-in function to be called only for failed requests
that match the template. The Error step provides an opportunity for you to
customize the error response.
- PostExit
-
void HTTPD_LINKAGE PostExitFunction (
unsigned char *handle,
long *return_code
)
A function defined for this step is called for each
request, regardless of the success or failure of the request. This step enables
you to do clean-up tasks for any resources allocated by your plug-in to process
the request.
- Server Termination
-
void HTTPD_LINKAGE ServerTermFunction (
unsigned char *handle,
long *return_code
)
A function defined for this step is called when an
orderly shutdown of the server occurs. It enables you to clean up resources
allocated during the Server Initialization step. Do not call any HTTP_* functions
in this step (the results are unpredictable). If you have more than one Caching Proxy API
directive in your configuration file for Server Termination, they will all
be called.
Note:
Because of a current limitation in Solaris code, the Server Termination
plug-in step is not executed when the ibmproxy -stop command is used to shut down the Caching Proxy on Solaris platforms. Refer to
the WebSphere Application Server Caching Proxy Administration Guide for information about starting and stopping the Caching Proxy.
HTTP return codes and values
These return codes follow the HTTP 1.1 specification, RFC 2616, published
by the World Wide Web Consortium (www.w3.org/pub/WWW/Protocols/). Your plug-in
functions must return one of these values.
Table 2. HTTP return codes for Caching Proxy API functions
Value |
Return code |
0 |
HTTP_NOACTION |
100 |
HTTP_CONTINUE |
101 |
HTTP_SWITCHING_PROTOCOLS |
200 |
HTTP_OK |
201 |
HTTP_CREATED |
202 |
HTTP_ACCEPTED |
203 |
HTTP_NON_AUTHORITATIVE |
204 |
HTTP_NO_CONTENT |
205 |
HTTP_RESET_CONTENT |
206 |
HTTP_PARTIAL_CONTENT |
300 |
HTTP_MULTIPLE_CHOICES |
301 |
HTTP_MOVED_PERMANENTLY |
302 |
HTTP_MOVED_TEMPORARILY |
302 |
HTTP_FOUND |
303 |
HTTP_SEE_OTHER |
304 |
HTTP_NOT_MODIFIED |
305 |
HTTP_USE_PROXY |
307 |
HTTP_TEMPORARY_REDIRECT |
400 |
HTTP_BAD_REQUEST |
401 |
HTTP_UNAUTHORIZED |
403 |
HTTP_FORBIDDEN |
404 |
HTTP_NOT_FOUND |
405 |
HTTP_METHOD_NOT_ALLOWED |
406 |
HTTP_NOT_ACCEPTABLE |
407 |
HTTP_PROXY_UNAUTHORIZED |
408 |
HTTP_REQUEST_TIMEOUT |
409 |
HTTP_CONFLICT |
410 |
HTTP_GONE |
411 |
HTTP_LENGTH_REQUIRED |
412 |
HTTP_PRECONDITION_FAILED |
413 |
HTTP_ENTITY_TOO_LARGE |
414 |
HTTP_URI_TOO_LONG |
415 |
HTTP_BAD_MEDIA_TYPE |
416 |
HTTP_BAD_RANGE |
417 |
HTTP_EXPECTATION_FAILED |
500 |
HTTP_SERVER_ERROR |
501 |
HTTP_NOT_IMPLEMENTED |
502 |
HTTP_BAD_GATEWAY |
503 |
HTTP_SERVICE_UNAVAILABLE |
504 |
HTTP_GATEWAY_TIMEOUT |
505 |
HTTP_BAD_VERSION |
Predefined functions and macros
You can call the server's
predefined functions and macros from your own plug-in functions. You must
use their predefined names and follow the format described below. In the parameter
descriptions, the letter i indicates an input parameter, the letter o indicates an output parameter, and i/o indicates that a
parameter is used for both input and output.
Each of these functions returns one of the HTTPD return codes, depending
on the success of the request. These codes are described in Return codes from predefined functions and macros.
Use the handle provided to your plug-in as the first parameter when calling
these functions. Otherwise, the function returns an HTTPD_PARAMETER_ERROR
error code. NULL is not accepted as a valid handle.
- HTTPD_authenticate()
- Authenticates a user ID or password, or both. Valid only in PreExit,
Authentication, Authorization, and PostAuthorization steps.
void HTTPD_LINKAGE HTTPD_authenticate (
unsigned char *handle, /* i; handle */
long *return_code /* o; return code */
)
- HTTPD_cacheable_url()
- Returns whether the specified URL content is cacheable according to
the Caching Proxy's standards.
void HTTPD_LINKAGE HTTPD_cacheable_url (
unsigned char *handle, /* i; handle */
unsigned char *url, /* i; URL to check */
unsigned char *req_method, /* i; request method for the URL */
long *retval /* o; return code */
)
The return value HTTPD_SUCCESS indicates that the URL
content is cacheable; HTTPD_FAILURE indicates the content is not cacheable.
HTTPD_INTERNAL_ERROR also is a possible return code for this function.
- HTTPD_close()
- (Valid only in the Transmogrifier step.) Transfers control to the next close routine in the stream stack. Call this function
from the Transmogrifier open, write, or close functions after any desired
processing is done. This function notifies the proxy server that the response has
been processed and the Transmogrifier step is complete.
void HTTPD_LINKAGE HTTPD_close (
unsigned char *handle, /* i; handle */
long *return_code /* o; return code */
)
- HTTPD_exec()
- Executes a script to satisfy
this request. Valid in the PreExit, Service, PostAuthorization, and Error
steps.
void HTTPD_LINKAGE HTTPD_exec (
unsigned char *handle, /* i; handle */
unsigned char *name, /* i; name of script to run */
unsigned long *name_length, /* i; length of the name */
long *return_code /* o; return code */
)
- HTTPD_extract()
- Extracts the value of a variable associated with this request. The valid
variables for the name parameter are the same
as those used in the CGI. See Variables for more information.
Note that this function is valid in all steps; however, not all variables
are valid in all steps.
void HTTPD_LINKAGE HTTPD_extract (
unsigned char *handle, /* i; handle */
unsigned char *name, /* i; name of variable to extract */
unsigned long *name_length, /* i; length of the name */
unsigned char *value, /* o; buffer in which to put
the value */
unsigned long *value_length, /* i/o; buffer size */
long *return_code /* o; return code */
)
If this function returns the code HTTPD_BUFFER_TOO_SMALL,
the buffer size you requested was not big enough for the extracted value.
In this case, the function does not use the buffer but updates the value_length
parameter with the buffer size that you need in order to successfully extract
this value. Retry the extraction with a buffer that is at least as big as
the returned value_length.
Note:
If the variable being extracted
is for an HTTP header, the HTTPD_extract() function will extract only the
first matching occurrence, even if the request contains multiple headers with
the same name. The httpd_getvar() function can be used instead of HTTPD_extract(),
and also offers other benefits. Refer to the section on the
httpd_getvar() function for
more information.
- HTTPD_file()
- Sends a file to satisfy this request. Valid only in the PreExit, Service,
Error, PostAuthorization, and Transmogrifier steps.
void HTTPD_LINKAGE HTTPD_file (
unsigned char *handle, /* i; handle */
unsigned char *name, /* i; name of file to send */
unsigned long *name_length, /* i; length of the name */
long *return_code /* o; return code */
)
-
httpd_getvar()
- The same as HTTPD_extract(), except that it is easier to use because
the user does not have to specify lengths for the arguments.
const unsigned char * /* o; value of variable */
HTTPD_LINKAGE
httpd_getvar(
unsigned char *handle, /* i; handle */
unsigned char *name, /* i; variable name */
unsigned long *n /* i; index number for the array
containing the header */
)
The index for the array containing the header begins with 0. To
obtain the first item in the array, use the value 0 for n; to obtain
the fifth item, use the value 4 for n.
Note:
Do not
discard or change the contents of the returned value. The returned string
is null terminated.
- HTTPD_log_access()
- Writes a string to the server's access log.
void HTTPD_LINKAGE HTTPD_log_access (
unsigned char *handle, /* i; handle */
unsigned char *value, /* i; data to write */
unsigned long *value_length, /* i; length of the data */
long *return_code /* o; return code */
)
Note that escape symbols are not required when writing the percent symbol (%) in server access logs.
- HTTPD_log_error()
- Writes a string to the server's error log.
void HTTPD_LINKAGE HTTPD_log_error (
unsigned char *handle, /* i; handle */
unsigned char *value, /* i; data to write */
unsigned long *value_length, /* i; length of the data */
long *return_code /* o; return code */
)
Note that escape symbols are not required
when writing the percent symbol (%) in server error logs.
- HTTPD_log_event()
- Writes a string to the server's event log.
void HTTPD_LINKAGE HTTPD_log_event (
unsigned char *handle, /* i; handle */
unsigned char *value, /* i; data to write */
unsigned long *value_length, /* i; length of the data */
long *return_code /* o; return code */
)
Note that escape symbols are not required when writing the percent symbol (%) in server event logs.
- HTTPD_log_trace()
- Writes a string to the server's trace log.
void HTTPD_LINKAGE HTTPD_log_trace (
unsigned char *handle, /* i; handle */
unsigned char *value, /* i; data to write */
unsigned long *value_length, /* i; length of the data */
long *return_code /* o; return code */
)
Note that escape symbols are not required
when writing the percent symbol (%) in server trace logs.
- HTTPD_open()
- (Valid only in the Transmogrifier step.) Transfers control to the next
routine in the stream stack. Call this from the Transmogrifier open, write,
or close functions after any desired headers are set and you are ready to
begin the write routine.
void HTTPD_LINKAGE HTTPD_open (
unsigned char *handle, /* i; handle */
long *return_code /* o; return code */
)
- HTTPD_proxy()
- Makes a proxy request. Valid in the PreExit, Service, and PostAuthorization
steps.
Note:
This is a completion function; the request is complete
after this function.
void HTTPD_LINKAGE HTTPD_proxy (
unsigned char *handle, /* i; handle */
unsigned char *url_name, /* i; URL for the
proxy request */
unsigned long *name_length, /* i; length of URL */
void *request_body, /* i; body of request */
unsigned long *body_length, /* i; length of body */
long *return_code /* o; return code */
)
- HTTPD_read()
- Reads the body of the client's request. Use HTTPD_extract() for headers.
Valid only in the PreExit, Authorization, PostAuthorization, and Service steps
and is useful only if a PUT or POST request has been done. Call this function
in a loop until HTTPD_EOF is returned. If there is no body for
this request, this function fails.
void HTTPD_LINKAGE HTTPD_read (
unsigned char *handle, /* i; handle */
unsigned char *value, /* i; buffer for data */
unsigned long *value_length, /* i/o; buffer size
(data length) */
long *return_code /* o; return code */
)
- HTTPD_restart()
- Restarts the server after all active requests have been processed. Valid
in all steps except for Server Initialization, Server Termination, and Transmogrifier.
void HTTPD_LINKAGE HTTPD_restart (
long *return_code /* o; return code */
)
-
HTTPD_set()
- Sets the value of a variable associated with this request. The variables
that are valid for the name parameter are the
same as those used in the CGI. See Variables for more information.
Note that you can also create variables with this function. Variables
that you create are subject to the conventions for HTTP_ and PROXY_ prefixes,
which are described in Variables. If you create a variable
that begins with HTTP_, it is sent as a header in the response to the client,
without the HTTP_ prefix. For example, to set a Location header, use HTTPD_set()
with the variable name HTTP_LOCATION. Variables created with a PROXY_ prefix
are sent as headers in the request to the content server. Variables created
with a CGI_ prefix are passed to CGI programs.
This function is valid
in all steps; however, not all variables are valid in all steps.
void HTTPD_LINKAGE HTTPD_set (
unsigned char *handle, /* i; handle */
unsigned char *name, /* i; name of value to set */
unsigned long *name_length, /* i; length of the name */
unsigned char *value, /* i; buffer with value */
unsigned long *value_length, /* i; length of value */
long *return_code /* o; return code */
)
Note:
You can use the httpd_setvar() function
to set a variable value without having to specify a buffer and length. Refer
to the section on
httpd_setvar() function for information.
- httpd_setvar()
- The same as HTTPD_set(), except that it is easier to use because the
user does not have to specify lengths for the arguments.
long /* o; return code */
HTTPD_LINKAGE httpd_setvar (
unsigned char *handle, /* i; handle */
unsigned char *name, /* i; variable name */
unsigned char *value, /* i; new value */
unsigned long *addHdr /* i; add header or replace it */
)
The addHdr parameter has four possible
values:
- HTTPD_SETVAR_REPLACE -- Replace all occurrences of the header variable
with the new value.
- HTTPD_SETVAR_REPLACE_ADD -- If the header variable exists, replace
its first occurrence with the new value; if the variable does not exist, append
the new value to the headers.
- HTTPD_SETVAR_ADD -- Append this value to the headers.
- HTTPD_SETVAR_REMOVE_ALL -- Delete all occurrences of this header
variable.
These values are defined in HTAPI.h.
- httpd_variant_insert()
- Inserts a variant into the cache.
void HTTPD_LINKAGE httpd_variant_insert (
unsigned char *handle, /* i; handle */
unsigned char *URI, /* i; URI of this object */
unsigned char *dimension, /* i; dimension of variation */
unsigned char *variant, /* i; value of the variant */
unsigned char *filename, /* i; file containing the object */
long *return_code /* o; return code */
)
Notes:
- The dimension argument refers to the header by which this object varies
from the URI. For instance, in the example above, a possible dimension value
is User-Agent.
- The variant argument refers to the value of the header for the header
given in the dimension argument. This varies from the URI. For instance, in
the example above, a possible value for the variant argument is the following:
Mozilla 4.0 (compatible; BatBrowser 94.1.2; Bat OS)
- The filename argument must point to a null-terminated copy of the file
name in which the user has saved the modified content. The user is responsible
for removing the file; this action is safe after return from this function.
The file contains only the body with no headers.
- When caching variants, the server updates the content-length header and
adds a Warning: 214 header. Strong entity tags are removed.
- httpd_variant_lookup()
- Determines if a given variant exists in the cache.
void HTTPD_LINKAGE httpd_variant_lookup (
unsigned char *handle, /* i; handle */
unsigned char *URI, /* URI of this object */
unsigned char *dimension, /* i; dimension of variation */
unsigned char *variant, /* i; value of the variant */
long *return_code); /* o; return code */
- HTTPD_write()
- Writes the body of the response. Valid in the PreExit, Service, Error,
and Transmogrifier steps.
If you do not set the content type before calling
this function for the first time, the server assumes that you are sending
a CGI data stream.
void HTTPD_LINKAGE HTTPD_write (
unsigned char *handle, /* i; handle */
unsigned char *value, /* i; data to send */
unsigned char *value_length, /* i; length of the data */
long *return_code); /* o; return code */
Note:
To set response headers, refer to the section on the
HTTPD_set() function.
Note:
After an HTTPD_* function returns, it is safe for you to free
any memory that you passed with it.
Return codes from predefined functions and macros
The server will set the return code parameter
to one of these values, depending on the success of the request:
Table 3. Return codes
Value |
Status code |
Explanation |
-1 |
HTTPD_UNSUPPORTED |
The function is not supported. |
0 |
HTTPD_SUCCESS |
The function succeeded, and the output fields are
valid. |
1 |
HTTPD_FAILURE |
The function failed. |
2 |
HTTPD_INTERNAL_ERROR |
An internal error was encountered and processing
for this request cannot continue. |
3 |
HTTPD_PARAMETER_ERROR |
One or more invalid parameters was passed. |
4 |
HTTPD_STATE_CHECK |
The function is not valid in this process step. |
5 |
HTTPD_READ_ONLY |
(Returned only by HTTPD_set and httpd_setvar.) The
variable is read-only and cannot be set by the plug-in. |
6 |
HTTPD_BUFFER_TOO_SMALL |
(Returned by HTTPD_set, httpd_setvar, and HTTPD_read.)
The buffer provided was too small. |
7 |
HTTPD_AUTHENTICATE_FAILED |
(Returned only by HTTPD_authenticate.) The authentication
failed. Examine the HTTP_RESPONSE and HTTP_REASON variables for more information. |
8 |
HTTPD_EOF |
(Returned only by HTTPD_read.) Indicates the end
of the request body. |
9 |
HTTPD_ABORT_REQUEST |
The request was aborted because the client provided
an entity tag that did not match the condition specified by the request. |
10 |
HTTPD_REQUEST_SERVICED |
(Returned by HTTPD_proxy.) The function that was
called completed the response for this request. |
11 |
HTTPD_RESPONSE_ALREADY_COMPLETED |
The function failed because the response for that
request has already been completed. |
12 |
HTTPD_WRITE_ONLY |
The variable is write-only and cannot be read by
the plug-in. |
Caching Proxy configuration directives for API steps
Each step
in the request process has a configuration directive that you use to indicate
which of your plug-in functions you want to call and execute during that step.
You can add these directives to your server's configuration file (ibmproxy.conf)
by manually editing and updating it, or by using the API Request Processing
form in the Caching Proxy Configuration and Administration forms.
API usage notes
- Except for the Service and NameTrans directives, the API directives
for each step do not need to appear in any particular order in the configuration
file. Note that the order of multiple entries for one API directive is significant,
as described later in this list.
- It is not necessary to include an entry for every API step. If you do
not have a plug-in for a particular step, omit the corresponding directive
and the standard processing for that step will be used.
- The Service and NameTrans directives work like
the other mapping directives (for example, the Pass directive) and are dependent
on their occurrence and placement relative to other mapping directives within
the configuration file. For example, a rule for /cgi-bin/foo.so must appear
before the rule for /cgi-bin/*.
This means that the server processes the
Service, NameTrans, Exec, Fail, Map, Pass, Proxy, ProxyWAS, and Redirect directives
in their sequence within the configuration file. When the server successfully
maps a URL to a file, it does not read or process any other of these directives.
(The Map directive is an exception. Refer to the WebSphere Application Server Caching Proxy Administration Guide for complete information
about proxy server mapping rules.)
- You can have more than one configuration directive for a step. For
example, you can include two NameTrans directives, each pointing to a different
plug-in function. When the server performs the name translation step, it processes
your name translation functions in the order in which they appear within the
configuration file.
Note:
If a plug-in function provided with the Caching Proxy uses
the same API directive as a plug-in you have written, place your plug-in's
directive after the system plug-in directive.
- Certain plug-in functions do not have to be executed for every request:
- Several directives include a URL
mask. Specifying a URL mask with these directives causes the plug-in application
to be called only for requests whose URLs match that pattern. Refer to API directives and syntax for information about which steps
can use URL masks and to API directive variables for information about how
to use this feature.
- Specify an authentication scheme with the
Authentication directive to indicate that you want the plug-in to be called
only for certain types of authentication. Currently, only basic authentication
is supported by the HTTP protocol. See API directive variables for additional
information.
- If the server fails to load a specific plug-in function, or if you have
a ServerInit directive that does not return an OK return code, no other plug-in
functions for that compiled Caching Proxy plug-in are called. Any processing specific
to that plug-in that was done up to this point is ignored. Other Caching Proxy plug-ins
that you include in these directives, and their functions, are not affected.
API directives and syntax
These configuration file directives must appear in the ibmproxy.conf file
as one line, with no spaces other than those explicitly specified here. Although
line breaks appear for readability in some of the syntax examples, there must
be no spaces at those points in the actual directive.
Table 4. Caching Proxy plug-in API directives
ServerInit |
|
/path/file:function_name init_string |
PreExit |
|
/path/file:function_name |
Authentication |
type |
/path/file:function_name |
NameTrans |
/URL |
/path/file:function_name |
Authorization |
/URL |
/path/file:function_name |
ObjectType |
/URL |
/path/file:function_name |
PostAuth |
|
/path/file:function_name |
Service |
/URL |
/path/file:function_name |
Midnight |
|
/path/file:function_name |
Transmogrifier |
|
/path/file:open_function_name:
write_function_name: close_function_name:error_function |
|
|
|
Log |
/URL |
/path/file:function_name |
Error |
/URL |
/path/file:function_name |
PostExit |
|
/path/file:function_name |
ServerTerm |
|
/path/file:function_name |
ProxyAdvisor |
|
/path/file:function_name |
GCAdvisor |
|
/path/file:function_name |
API directive variables
The variables in these directives have the following meanings:
- type
- Used only with the Authentication directive to specify whether or not
your plug-in function is called. Valid values are the following:
- Basic -- The plug-in function is called only for basic authentication
requests.
- * -- The plug-in function is called for all requests. Currently,
only basic authentication is supported by HTTP protocol. For nonbasic authentication
requests, you can return an error code indicating that this type of authentication
is not supported.
- URL
- Specifies the requests for which your plug-in function is called. Requests
with URLs that match this template will cause the plug-in function to be used.
URL specifications in these directives are virtual (they do not include the
protocol) but are preceded by a slash (/). For example, /www.ics.raleigh.ibm.com
is correct, but http://www.ics.raleigh.ibm.com is not. You can specify this
value as a specific URL or as a template.
- path/file
- The fully qualified file name of your compiled program.
- function_name
- The name that you gave your plug-in function within your program.
The Service directive requires an asterisk (*) after the function name if
you want to have access to path information.
- init_string
- This optional part of the ServerInit directive can contain any text
that you want to pass to your plug-in function. Use httpd_getvar() to extract
the text from the INIT_STRING variable.
For additional information, including syntax, for these directives, see
the WebSphere Application Server Caching Proxy Administration Guide.
Compatibility with other APIs
The Caching Proxy API is backward-compatible with ICAPI and GWAPI, through version
4.6.1.
Porting CGI programs
Use the following guidelines for porting CGI applications
written in C to use the Caching Proxy API:
- Remove your main() entry point, or rename it so that you can build a DLL.
- Eliminate global variables or protect them with a mutual exclusion semaphore.
- Change the following calls in your programs:
- Change printf() header calls to HTTPD_set() or httpd_setvar().
- Change printf() data calls to HTTPD_write().
- Change getenv() calls to HTTPD_extract() or httpd_getvar(). Be aware that these calls will
return unallocated memory, so you must perform a free() call on the result to prevent
a memory leak.
- Remember that the server runs in a multithreaded environment, and your
plug-in functions must be thread safe. If the functions are reentrant, performance
does not decrease.
- Remember to set the Content-Type header if you are using HTTPD_write()
to send data back to the client.
- Check your code meticulously for memory leaks.
- Think about your error paths. If you generate error messages yourself
and send them back as HTML, you must return HTTPD_OK from your service function
or functions.
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.
Legend: 1--Client machine 2--Caching Proxy 3--Origin
server
- 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/.