Appendix B. Configuration file directives

This topic describes the directives contained in the ibmproxy.conf configuration file.

Use this information as a reference if you configure the server by editing the ibmproxy.conf file. If you use the Configuration and Administration forms, you do not need to refer to this chapter.

Directives are listed alphabetically.

Directives not changed on restart

Some directives are not refreshed when the server is restarted. If the following directives are changed while the server is running, you must manually stop and then manually start the server again. (See Starting and stopping Caching Proxy.)

Table 6. Directives not refreshed on a restart
Directive group Directives
CGI DisinheritEnv, InheritEnv
Caching Caching
Logging AccessLog, CacheAccessLog, ErrorLog, ProxyAccessLog, ServerRoot
Network Access BindSpecific, Hostname, ListenBacklog, Port
Performance MaxActiveThreads
RTSP All RTSP directives
SSL All SSL directives
Linux and UNIX Process Control GroupId, UserId
Miscellaneous TransparentProxy

Overview of directives

This appendix provides the following information about each directive:

Acceptable values

The following list includes values that are accepted in the configuration file:

Syntax of configuration file records

When editing the configuration file, remember the following requirements:

Caching Proxy directives

The Caching Proxy directives follow.

AcceptAnything -- Serve all files

Use this directive to serve files to the client even if the MIME type of the file does not match an ACCEPT: header sent by the client. If this directive is set to OFF, files whose MIME types differ from the types that the client can accept are not displayed. An error page is displayed instead.

Format

AcceptAnything  {on | off}

Example

AcceptAnything off

Default

AcceptAnything on 

AccessLog -- Name the path for the access log file

Use this directive to specify the directory and file where you want the server to log access statistics. By default, the server writes an entry to this log each time a client sends the server a request for data stored on the local server. Typically, these entries include only requests from the configuration client or accesses when the Caching Proxy machine is used as an origin server. This log does not contain proxy or cache access information.

Use the NoLog directive to specify clients whose requests you do not to be logged. For a description of the NoLog directive, refer to NoLog -- Suppress log entries for specific hosts or domains that match a template.

The server starts a new log file each day at midnight if it is running. Otherwise, the server starts a new log file the first time you start it on any day. When creating the file, the server uses the file name you specify and appends a date suffix. The date suffix is in the format Mmmddyyyy, where Mmm is the first three letters of the month; dd is the day of the month; and yyyy is the year.

Note:
If you change the server defaults for the user ID, group ID, or log directory paths, create the new directories and update the permissions and ownership of the directories. To enable the server to write information to a user-defined log directory, set the permission for that directory as 755, and set the user-defined server user ID as the owner. For example, if you change the user ID of the server from the default to jdoe, and the default logs directory to server_root/account, then the server_root/account directory must have the permission 755 and be owned by jdoe.

It is a good idea to remove old log files because they can use a significant amount of space on your hard drive.

Format

AccessLog  /directory_path/logfile_name

Example

AccessLog  /logs/accesslog

Defaults

AccessLogExcludeMethod -- Suppress log entries for files or directories requested by a specified method

Use this directive to prevent the logging of requests made by a specific method for access to files or directories. For example, you might not want to log DELETE requests for files or directories.

You can have multiple occurrences of this directive in your configuration file. You can also put multiple methods on the same directive if you separate them by one or more spaces.

Format

AccessLogExcludeMethod method  [...]

Examples

AccessLogExcludeMethod GET  
AccessLogExcludeMethod PUT
AccessLogExcludeMethod POST
AccessLogExcludeMethod DELETE
AccessLogExcludeMethod GET   PUT

Default

None. The server includes in the access log the files and directories requested by all types of methods.

AccessLogExcludeMimeType -- Suppress Proxy access log entries for specific MIME types

Use this directive to specify that you do not want record in the Proxy access log requests for access to directories or files of a specified MIME type. (Examples of MIME types are text/html, image/gif, and image/jpeg.) For example, you might not want to log access requests for GIF images.

You can have multiple occurrences of this directive in your configuration file. You can also put multiple MIME types on the same directive if you separate them by one or more spaces.

Note:
This directive only affects the Proxy access log. It is not possible to filter a log listing these cached objects by their MIME type. Use AccessLogExcludeURL to do this.

Format

AccessLogExcludeMimeType MIME_type  [...]

Example

AccessLogExcludeMimeType image/gif
AccessLogExcludeMimeType text/html
AccessLogExcludeMimeType image/gif   text/html

Default

None. The access log includes requests to the server for files and directories of all MIME types.

AccessLogExcludeReturnCode -- Suppress log entries for specific return codes

Use this directive to specify that you do not want to log access requests that fall within a specified range of error code numbers. These error code numbers are proxy server status codes. You cannot specify individual codes. Specifying 300 indicates that you want to exclude access requests with redirection return codes (301, 302, 303, and 304).

You can have multiple occurrences of this directive in your configuration file. You can also put multiple return codes on the same directive if you separate them by one or more spaces.

Format

AccessLogExcludeReturnCode range

Example

AccessLogExcludeReturnCode 300

Default

None. The access log includes all requests to the server, regardless of the code.

AccessLogExcludeURL -- Suppress log entries for specific files or directories

Use this directive to specify that you do not want to log requests for access to specific files or directories that match a specified URL template. For example, you might not want to log access requests for GIF files, or you might not want to log access requests to a particular file or directory on your server.

You can have multiple occurrences of this directive in your configuration file. You can also put multiple entries for the same directive if you separate them by one or more spaces.

Format

AccessLogExcludeURL  file_or_type [...]

Examples

AccessLogExcludeURL  *.gif
AccessLogExcludeURL  /Freebies/*
AccessLogExcludeURL  *.gif   /Freebies/*

Default

None. The server logs requests for access to all files and directories.

AccessLogExcludeUserAgent -- Suppress log entries from specific browsers

Use this directive to specify that you do not want to log access requests made by specific user agents (for example, Internet Explorer 5.0).

You can have multiple occurrences of this directive in your configuration file. You can also put multiple entries for the same directive if you separate them by one or more spaces.

Format

AccessLogExcludeUserAgent user_agent [...]

Example

AccessLogExcludeUserAgent  *Mozilla/2.0
AccessLogExcludeUserAgent  *MSIE 5*

Default

By default, the ibmproxy.conf file contains the following definitions for the AccessLogExcludeUserAgent directive:

AccessLogExcludeUserAgent IBM_Network_Dispatcher_HTTP_Advisor
AccessLogExcludeUserAgent IBM_Network_Dispatcher_WTE_Advisor

The user agents listed above are those defined for certain Load Balancer advisors that typically sit in front of the Caching Proxy server. To improve performance by minimizing the number of writes to the log, these user agents are not logged. By default, the server logs access requests made by all other user agents.

AddBlankIcon -- Specify the URL for the icon used to align the headings of directory listings

Use this directive to specify an icon to use for aligning the headings on directory listings that are returned when the server acts as a proxy for FTP requests. The icons appear beside the associated files to help users differentiate the files.

The icon can either be a blank icon or another icon that you specify to appear on the headings of your directory listings. For proper alignment, the icon you use must be the same size as the other icons you are using on your directory listings.

Format

AddBlankIcon icon_URL   alternative_text
icon_URL

Specifies the last part of the URL for the icon. The server adds this value to the /icons/ directory to form the complete URL request. If the request is for a local file, the server translates the request through the mapping directives. For the icon to be retrieved, the mapping directives must allow the request to be passed.

If you are using the server as a proxy, the complete request must be a fully qualified URL pointing to your server.

alternative_text
Specifies the alternative text to use for the icon if the requesting browser is not displaying graphics.

Example

AddBlankIcon logo.gif  logo

Defaults

The default does not specify alternative text because the icon is blank.

AddDirIcon -- Specify the icon URL for directories on directory listings

Use this directive to specify an icon for representing a directory on a directory listing.

Format

AddDirIcon   icon_URL   alternatIve_text
icon_URL

Specifies the last part of the URL for the icon. The server adds this value to the /icons/ directory to form the complete URL request. If the request is for a local file, the server translates the request through the mapping directives. For the icon to be retrieved, the mapping directives must allow the request to be passed.

If you are using the server as a proxy, the complete request must be a fully qualified URL pointing to your server. You must map the URL to a local file and make sure that the mapping directives allow the URL to be passed.

alternative_text
Specifies the alternative text to use for the icon if the requesting browser is not displaying graphics.

Example

AddDirIcon  direct.gif  DIR

Defaults

AddEncoding -- Specify the MIME content encoding of files with particular suffixes

Use this directive to bind files with a particular suffix to a MIME encoding type. This directive is seldom used.

Format

AddEncoding .extension  encoding
.extension
Specifies the file suffix pattern.
encoding
Specifies the MIME encoding type that you want to bind to files that match the corresponding suffix pattern.

Example

AddEncoding .qp   quoted_printable

Default

AddEncoding .Z  x-compress

AddIcon -- Bind an icon to a MIME content type or encoding type

Use this directive to specify icons for representing files with a specific MIME content type or encoding type. The server uses the icons on directory listings, including FTP directory listings.

Format

AddIcon icon_URL  alternative_text  MIME_type_template
icon_URL

Specifies the last part of the URL for the icon. The server adds this value to the /icons/ directory to form the complete URL request. If the request is for a local file, the server translates the request through the mapping directives. For the icon to be retrieved, the mapping directives must allow the request to be passed.

If you are using the server as a proxy, the complete request must be a fully qualified URL pointing to your server. You must map the URL to a local file and make sure that the mapping directives allow the URL to be passed.

alternative_text
Specifies the alternative text to use for the icon if the requesting browser is not displaying graphics.
type_template
Specifies either a MIME content-type or encoding-type template. Content-type templates always contain a slash (/). Encoding-type templates never have a slash.

Example

AddIcon   video_file.m.pm.gif    MOV    video/*

Defaults

Numerous defaults are set for the AddIcon directive in the ibmproxy.conf configuration file.

AddLang -- directive for multi-format processing

Use the AddLang directive for processing files with multiple language formats. The directive enables users to associate the file extension with languages when requests are served locally.

The proxy server already supports AddType and AddEncoding directives for processing files with multiple formats. The proxy server cannot handle a multi-format serving that is based on the Accept-Langauge header in the requests. However, the AddLang directive, which was previously hidden, provides a mechanism to bind a language to a file extension.

Format

AddLang .file-extension language quality

Where language is used to match the values in Accept-Language header, and quality is a floating point number that is used to calculate the ranking for the mapped files.

Example

For example, assume that the following AddLang settings are configured:

AddLang .en en 1.001
AddLang .de de 1.0
AddLang .en en-us 0.9

Then, assume that the sample.html.en and sample.html.de files already exist on your local disk. The following request is received by Caching Proxy:

GET /sample.html HTTP/1.0 Accept-Language: de,en;q=0.5
..... 

When the request comes in, the proxy server computes a ranking for each mapped local file that is based on the values in the Accept-Langauge header and the definitions in AddLang directives. The file with highest ranking is used to serve the request.

In the previous example, the sample.html.en file is assigned the following ranking:

0.5 x 1.001 = 5.005

The sample.html.de file is assigned the following ranking:

0.5 x 1.0 =0.5
Note:
It is possible that two or more local files might receive the same ranking. In this case, the behavior is determined by the file order from the search results within the operating system. To avoid this problem, assign a slightly larger value for the language to which the system should default. In the previous example, for instance, setting 1.001 for the AddLang value of en would give it precedent over other languages with a value of 1.0.

Default

If a value is not specified for q in the Accept-Language header, the default value is 1.0.

AddParentIcon -- Specify the URL for the icon representing a parent directory on directory listings

Use this directive to specify an icon for representing a parent directory on directory listings.

Format

AddParentIcon   icon_URL   alternative_text
icon-URL

Specifies the last part of the URL for the icon. The server adds this value to the /icons/ directory to form the complete URL request. If the request is for a local file, the server translates the request through the mapping directives. For the icon to be retrieved, the mapping directives must allow the request to be passed.

If you are using the server as a proxy, the complete request must be a fully qualified URL pointing to your server. You must map the URL to a local file and make sure that the mapping directives allow the URL to be passed.

alternative_text
Specifies the alternative text to use for the icon if the requesting browser is not displaying graphics.

Example

AddParentIcon  parent.gif  UP

Default

AddParentIcon   dir-up.gif    UP

AddType -- Specify the data type of files with particular suffixes

Use this directive to bind files with a particular suffix to a MIME type and subtype. You can have multiple occurrences of this directive in your configuration file. The server provides defaults for the most-commonly used suffixes.

Format

AddType .extension type/subtype encoding [quality[ character_set]]
.extension
The file suffix pattern. You can use the wildcard character (*) only on the following two special suffix patterns:
*.*
Matches all file names that contain a dot character (.) and are not matched by other rules.
*
Matches all file names that do not contain a dot character (.) and are not matched by other rules.
type/subtype
The MIME type and subtype you want to bind to files that match the corresponding suffix pattern.
encoding
The MIME content encoding to which the data has been converted. Encoding is also used by an FTP proxy server to determine whether the file is retrieved in binary mode. In most cases, the appropriate encoding is 7bit, 8bit, or binary, and is determined as follows:
7bit
Data is all represented as short (less than 1000 characters) lines of 8859-1 ASCII data. Source code or plain text files usually fall into this category. Exceptions are files containing line-drawing characters or accented characters.
8bit
Data is represented as short lines, but can contain characters with the high bit set (for example, line-drawing characters or accented characters). PostScript files and text files from European sites usually fall into this category.
binary
This encoding can be used for all data types. Data can contain not only non-ASCII characters but also long (greater than 1000 characters) lines. Almost every file of type image/*, audio/*, and video/* falls into this category, as do binary data files of type application/*.

Any other value of encoding receives the same treatment as binary and is passed in MIME headers as a content encoding MIME header. The specification 7bit and 8bit is not sent in MIME headers.

quality
Specifies an optional indicator of relative value (on a scale of 0.0 to 1.0) for the content type. The quality value is used if multiple representations of a file are matched by a request. The server selects the file that is associated with the highest quality value. For example, if the file internet.ps is requested, and the server has the following AddType directives set, the server uses the application/postscript line because its quality number is higher.
AddType  .ps application/postscript  8bit  1.0
AddType  *.* application/binary   binary 0.3
character_set
An optional indicator of the character set you want to associate with text files. For the files to which you assign a character set, the server tells client browsers which character set to use when displaying the file. If you set a value for the character_set field, you must also include a value for the quality field.

Example

AddType .bin  application/octet-stream binary  0.8

Defaults

Numerous default settings for the AddType directive are contained in the configuration file (ibmproxy.conf).

AddUnknownIcon -- Specify the icon URL for unknown file types on directory listings

Use this directive to specify an icon for representing files with an unknown file type on a directory listing.

Format

AddUnknownIcon   icon_URL   alternative_text
icon_URL

Specifies the last part of the URL for the icon. The server adds this value to /icons/ to form the complete URL request. If the request is for a local file, the server translates the request through the mapping directives. For the icon to be retrieved, the mapping directives must allow the request to be passed.

If you are using the server as a proxy, the complete request must be a fully qualified URL pointing to your server. You must map the URL to a local file and make sure that the mapping directives allow the URL to be passed.

alternative_text
Specifies the alternative text to use for the icon if the requesting browser is not displaying graphics.

Example

AddUnknownIcon saywhat.gif  unknown

Defaults

AdminPort -- Specify the port for requesting administrative pages or forms

Use this directive to specify a port that administrators can use to access server status pages or configuration forms. Requests to this port are not queued with all other incoming requests on the standard port or ports that are defined with the Port directive. However, requests on the AdminPort go through the same normal access-control and request-mapping rules as, for example, Pass, Exec, Protect.

Note:
The administration port must not be the same as the standard port or ports defined with the Port directive.

Format

AdminPort port_number

Example

AdminPort 2001

Default

AdminPort 8008

AggressiveCaching -- Specify caching for noncacheable files

Use this directive to specify whether files returned by the origin server and marked noncacheable are to be cached anyway. Noncacheable files that are cached according to this directive are marked as must revalidate. Each time the file is requested, the proxy server sends an If-Modified-Since request to the origin server to revalidate the response before the response is served from the cache. Currently, the only noncacheable files affected by this directive are responses from the origin server that contain a cache-control: no-cache header. This directive can be specified multiple times.

Format

AggressiveCaching url_pattern 

Examples

AggressiveCaching http://www.hosta.com/*
AggressiveCaching http://www.hostb.com/* 

For backwards compatibility, the previous syntax for this directive (AggressiveCaching {on | off}) is now treated as follows:

Note:
If both AggressiveCaching off and AggressiveCaching url_pattern are specified, AggressiveCaching off is ignored, and a warning message is displayed.

Default

None

appendCRLFtoPost -- Append CRLF to POST requests

Use this directive to specify URLs for which Caching Proxy appends the carriage return and line-feed characters to the end of the body of a POST request. This directive can be specified multiple times.

Note:
Specify this directive only for URLs that have a known problem processing POST requests.

Format

appendCRLFtoPost  url_pattern

Example

appendCRLFtoPost http://www.hosta.com/

Default

None

ArrayName -- Name the remote cache array

Use this directive to specify the remote cache array to be shared by the servers.

Note:
When setting up an array, configure the Hostname directive identically on all members of the array.

Format

ArrayName array_name

Default

None

Authentication -- Customize the Authentication step

Use this directive to specify a customized application function you want the server to call during the Authentication step of the server request process. This code is executed according to the authentication scheme. Only BASIC authentication is supported.

Note:
Authentication is part of the authorization process; it occurs only when authorization is required.

Format

Authentication type /path/file:function_name
type
Specifies an authentication scheme that further determines whether your application function is called. Both an asterisk (*) and BASIC are accepted values.
/path/file
Specifies the fully qualified file name of the compiled program, including the extension.
function_name
Specifies the name you give to the application function within your program.

Example

Authentication BASIC /ics/api/bin/icsextpgm.so:basic_authentication

Default

None

Authorization -- Customize the Authorization step

Use this directive to specify a customized application function that the server calls during the Authorization step of the server request process. This code verifies that the requested object can be served to the client.

Format

Authorization request_template /path/file:function_name
request_template
Specifies a template for requests that further determine whether your application function is called. The specification can include the protocol, domain, and host; it can be preceded by a slash character (/) and can use an asterisk (*) as a wildcard. For example, /front_page.html, http://www.ics.raleigh.ibm.com, /pub*, /*, and * are all valid. The request template must start at the document root (/) when using Caching Proxy as a reverse proxy.
/path/file
Specifies the fully qualified file name of the compiled program, including the extension.
function_name
Specifies the name you give your application function within your program.

Example

Authorization /index.html /api/bin/icsextpgm.so:auth_url

Default

None

AutoCacheRefresh -- Specify whether cache refreshing is to be used

Use this directive to turn cache refreshing on or off. If refreshing is turned on, the cache content is refreshed automatically. If refreshing is turned off, the cache agent is not invoked and all of its settings are ignored. If you are starting the cache agent by another method, for example, by using a cron job on Linux and UNIX systems, set this directive to off.

Format

AutoCacheRefresh {on | off}

Default

AutoCacheRefresh On

BindSpecific -- Specify whether the server binds to one or all IP addresses

Use this directive on a multihomed system to specify whether the server listens on a single network address. If you set the value to On, the server binds to the IP address specified in the Hostname directive, instead of binding to all local IP addresses.

If this directive is not specified, the server binds to the default Hostname.

If you change this directive, you must manually stop and then start the server again. The server does not make the change if you only restart it. (See Starting and stopping Caching Proxy.)

Format

BindSpecific {on | off}  [OutgoingSrcIp ip_addr | host_name]
[OutgoingSrcIp ip_addr | host_name]
The OutgoingSrcIp options allows Caching Proxy to use a specific source IP address when making outgoing connections. It is useful for Caching Proxy settings in DMZ and when special firewall rules requires this.

Default

BindSpecific Off

BlockSize -- Specify the size of blocks in the cache

This directive specifies the size (in bytes) of blocks in the medium of the caching device. By default, the value is 8192. Because it is the only size supported, do not change the value. For more information, see the reference section for htcformat command.

Format

BlockSize size

Default

By default, there is no setting for BlockSize in the configuration file. (The default value is 8192.)

CacheAccessLog -- Specify the path for the cache access log files

Use this directive to specify the path and file name where you want the server to store a log of accesses to the proxy cache. This directive is valid only if the server is running as a proxy. See CacheRefreshTime -- Specify when to start the cache agent for more information.

To enable logging of requests to the proxy cache, the Caching directive must be set to ON, and values must be set for the CacheMemory and the CacheAccessLog directives. Optionally, one or more cache devices can be defined by using the CacheDev directive.

The value of CacheAccessLog can be either an absolute path or a path relative to ServerRoot. (One example is shown of each.)

Format

CacheAccessLog  path/file

Examples

CacheAccessLog  /absolute/path/logfile
CacheAccessLog  /logs/logfile

Defaults

CacheAlgorithm -- Specify the cache algorithm

Use this directive to specify the cache algorithm that the server uses during garbage collection.

Format

CacheAlgorithm  {bandwidth | responsetime | blend} 
bandwidth
Attempts to maximize the saving of network bandwidth.
responsetime
Attempts to minimize user response time.
blend
Uses a balanced combination of bandwidth and responsetime.

Default

CacheAlgorithm bandwidth

CacheByIncomingUrl -- Specify the basis for generating cache file names

Use this directive to specify whether the generated cache file names are based on the incoming URL of the request.

If this directive is set to on, the cache file names are generated based on the incoming URL. If this directive is set to off, the incoming URL is first passed through all applicable name translation plugins, MAP rules, and PROXY rules, and the generated cache file name is based on the resulting URL.

Note:
When defining the cache filters, in a reverse proxy scenario for URL-based cache filters, use a format starting with a document root of / (forward slash). For example: /test/index.html. The format should not include a protocol, for example, http://.

Format

CacheByIncomingUrl {on | off}

Default

CacheByIncomingURL off

CacheClean -- Specify how long to keep cached files

Use this directive to specify how long you want the server to keep cached files. When garbage collection runs, the server deletes cached files that have exceeded this time, regardless of the files' expiration date. Any time a file is requested that has been in the cache longer than the specified time, the server will revalidate the file to ensure it is valid before serving it.

Format

CacheClean  time_specification

Example

CacheClean 2 weeks

Default

CacheClean 1 month

CacheDefaultExpiry -- Specify the default expiration time for files

Use this directive to set a default expiration time for files for which the server did not provide either an Expires or a Last-Modified header. Specify a URL template and the expiration time for files with URLs that match the template. Multiple occurrences of this directive can be included in the configuration file. Include a separate directive for each template. The URL template must include the protocol. Specify the time value in any combination of months, weeks, days, and hours.

Format

CacheDefaultExpiry URL_template expiration_time

Defaults

CacheDefaultExpiry ftp:*  1 day
CacheDefaultExpiry gopher:*  2 days
CacheDefaultExpiry http:*  0 days
Note:
The default expiration for the HTTP protocol is 0 days. Keeping this value is recommended because many script programs do not give an expiration date, yet their output expires immediately. A value other than 0 can cause clients to see out-of-date content.

CacheDev -- Specify a storage device for the cache

Use this directive to specify a cache storage device. Either a file or a raw disk partition can be specified. On AIX platforms, a raw logical volume can be specified. (If a memory cache is not used, raw disk caching yields the best performance.)

Note that cache devices must be prepared before they are specified. To prepare a cache device, format it by using the htcformat command. For more information, see htcformat command.

Multiple cache devices can be specified. Each device is associated with the same CacheMemory and BlockSize values. However, each cache device incurs a memory overhead in the proxy server machine of about 8 MB. Fewer large devices are more efficient than more smaller devices. For best efficiency, use an entire disk as one large partition with nothing else on the disk. More information about cache storage is included in Optimizing disk cache performance.

Format

CacheDev  {raw_disk_partition | file}

Examples

AIX: CacheDev /dev/rlv02

HP-UX: CacheDev /dev/rdsk/c1t15d0

Linux: CacheDev /opt/IBMWTE/filecache1

Solaris: CacheDev /dev/rdsk/clt3d0s0

Windows: CacheDev \\.\E:

Default

None

CacheExpiryCheck -- Specify whether the server returns expired files

Use this directive to specify whether the server returns cached files that have expired. Set the value to Off if you want the server to be able to return expired files. Use the default value of On if you want the proxy to check with the origin server for a more recent version when a client requests an expired file. Generally, administrators do not want the server to return expired files except possibly when they are demonstrating the server and do not particularly care about the content being returned.

Format

CacheExpiryCheck {on | off}

Default

CacheExpiryCheck On

CacheFileSizeLimit -- Specify the maximum size for files to be cached

Use this directive to specify the maximum size of files to be cached. Files larger than this size are not cached. The value can be specified in bytes (B), kilobytes (K), megabytes (M), or gigabytes (G). It does not matter whether the specification includes a space between the number and the unit of measurement (B, K, M, G).

Format

CacheFileSizeLimit maximum {B | K | M | G}

Default

CacheFileSizeLimit 4000 K

CacheLastModifiedFactor -- Specify the value for determining expiration dates

Use this directive to specify the value to use for calculating expiration dates for specific URLs or for all the URLs that match a template.

HTTP servers frequently give the last-modified time for a file but not an expiration date. Similarly, FTP files can have a last-modified time stamp, but not an expiration date. Caching Proxy calculates an expiration date for these files based on the last-modified time. It uses the last-modified time to determine the length of time since the file was modified and multiplies that by the value on a CacheLastModifiedFactor directive. The result of this calculation is the lifetime of the file, or the length of time before the file becomes stale.

You can also specify off or -1 to turn the directive off and not calculate an expiration date. The proxy server reads the CacheLastModifiedFactor directives in the order they appear in the configuration file. It uses the first directive that it can apply to the cached file.

Format

CacheLastModifiedFactor url factor
url
Specifies the full URL, including the protocol, of the file being cached. You can use a URL template with asterisks (*) as wildcards, to apply a mask.
factor
Specifies the factor to use in the calculation. The values off or -1 can also be specified.

Examples

CacheLastModifiedFactor  *://hosta/*    off
CacheLastModifiedFactor  ftp://hostb/*  0.30
CacheLastModifiedFactor  ftp://*        0.25
CacheLastModifiedFactor  http://*       0.10
CacheLastModifiedFactor  *              0.50

Defaults

CacheLastModifiedFactor http://*/ 0.10
CacheLastModifiedFactor http://*.htm* 0.20
CacheLastModifiedFactor http://*.gif 1.00
CacheLastModifiedFactor http://*.jpg 1.00
CacheLastModifiedFactor http://*.jpeg 1.00
CacheLastModifiedFactor http://*.png 1.00
CacheLastModifiedFactor http://*.tar 1.00
CacheLastModifiedFactor http://*.zip 1.00
CacheLastModifiedFactor http:* 0.15
CacheLastModifiedFactor ftp:*  0.50
CacheLastModifiedFactor     *  0.10

The default of 0.14 causes files modified a week ago to expire in one day.

CacheLocalDomain -- Specify whether to cache the local domain

Use this directive to specify whether to cache URLs from hosts in the same domain as the proxy. Local sites on an intranet usually do not need to be cached because the internal bandwidth is sufficient to load URLs quickly. Not caching local sites saves cache space for URLs that take longer to retrieve.

Format

CacheLocalDomain {on | off}

Default

CacheLocalDomain on

CacheMatchLanguage -- Specify the language preference for the returned cache content

If the backend server has the capability of returning language variants to customers for the same URL, use this directive to support caching different languages for the same URL. The directive allows Caching Proxy to verify the language preference in the requests with the language of the cached response.

When CacheMatchLanguage is enabled, before Caching Proxy loads the cached content, it compares the language preference in your request's Accept-Language header with the language of the cached content. Caching Proxy also compares the preference distance. If a preference distance is less than a specified limit, it returns the cached copy; otherwise, the proxy forwards the request to the backend server to get a fresh copy in your requested language.

Format

CacheMatchLanguage {on | off}  lang-prefer-distance-limit special-id-for-all-lang
lang-prefer-distance-limit
Specify a value within the range of 0.001- 0.9999.
special-id-for-all-lang
Specify a language string returned from the server in the Content-Language header to inform the proxy that the response could be used for all language preferences.

Examples

The following is a configuration example of the directive, cache object, and the request.

CacheMatchLanguage On 0.2

If the cache object is simplified Chinese (zh_cn) and the request is:

GET / HTTP/1.1 
... 
Accept-Language: en_US;q=1.0, zh_cn;q=0.7, ja;q=0.3 
.... 

For this request, the customer requests a page in English (with code and quality en_US/1.0), then simplified Chinese (with code and quality zh_cn/0.7), and then Japanese (its code and quality is ja/0.3). The cached object is in simplified Chinese. The preference distance between best expected quality and matched language quality is 1.0 - 0.7 = 0.3. Because the limit is set to 0.2 by the CacheMatchLanguage directive, and 0.3 is greater than the limit, the proxy asks the server for a new copy of that URL instead of returning the cached object.

If the server does not specify a language or does not specify special-id-for-all-lang in the Content-Language header when returning a response, when the next request comes in, the proxy does not match language preference and returns the cached copy.

Default

CacheMatchLanguage off

CacheMaxExpiry -- Specify the maximum lifetime for cached files

Use this directive to define the maximum length of time files can stay in the cache. The lifetime of a cached file defines the length of time it can be served from the cache without checking the origin for updates. In some cases, the computed lifetime for a cached file can be longer than you want to keep the file. The lifetime of the file, either specified by the origin or computed by Caching Proxy, cannot exceed the limit specified by the CacheMaxExpiry directive.

Multiple occurrences of this directive are allowed in the configuration file. Include a separate directive for each template.

Format

CacheMaxExpiry URL lifetime
URL
Specifies a fully specified URL, including the protocol, of the file being cached. You can use a URL template with asterisks (*) as wildcards, to apply a mask.
lifetime
Specifies the maximum lifetime for cached files matching the URL template. The time can be specified in any combination of months, weeks, days, hours, minutes, or seconds.

Examples

CacheMaxExpiry ftp:* 1 month
CacheMaxExpiry http://www.santaclaus.np/* 2 days 12 hours

Default

CacheMaxExpiry 1 month

CacheMemory -- Specify the cache RAM

Use this directive to specify the amount of memory to associate with the cache. For optimum performance of disk caches, a minimum cache memory value of 64 MB is recommended for cache infracture support, including the cache index. As the cache size increases, the cache index increases, and more cache memory is required to store the index. A cache memory value of 64 MB is large enough to provide cache infrastructure support and store a cache index for a disk cache of up to approximately 6.4 GB. For larger disk caches, the cache memory should be 1% of the cache size.

If memory caching is used, set this directive to include both the cache and the amount of memory needed for the cache index.

The maximum recommended value for this directive is 1600 MB. This limit is determined by the fact that Caching Proxy, as a 32-bit application, can use a maximum of 2 GB of memory. If the amount of memory required for the cache plus the amount of memory used for routine processing approaches or exceeds 2 GB, Caching Proxy does not operate normally.

The amount can be specified in one of the following units: bytes (B), kilobytes (K), megabytes (M), and gigabytes (G).

Format

CacheMemory amount {B | K | M | G}

Default

CacheMemory 64 M

CacheMinHold -- Specify how long to keep files available

Use this directive to specify URLs for files whose expiration is to be overridden. Some sites set files to expire before the end of their lifetime, requiring the server to request the file more frequently. The CacheMinHold directive causes the expired file to be held in the cache for the specified amount of time before it is requested again. This directive can be specified multiple times.

Note:
If expiration dates are overridden, the files in the cache can become obsolete or out-of-date.

Example

CacheMinHold http://www.cachebusters.com/* 1 hour

Default

None

CacheNoConnect -- Specify the stand-alone cache mode

Use this directive to specify whether the proxy server retrieves files from remote servers. The default value (Off) enables the server to retrieve files from remote servers. The value On sets the server to run in stand-alone cache mode. This means that the server can return only files already stored in its cache. Typically, when running the server in this mode, you also set the CacheExpiryCheck directive to Off.

Running the server in stand-alone cache mode can be useful if you are using the server for demonstrations. If you know that all the files you want to use for a demonstration are stored in the cache, then you do not need a network connection.

Format

CacheNoConnect  {on | off}

Default

CacheNoConnect Off

CacheOnly -- Cache only the files with URLs that match a template

Use this directive to specify that only files with URLs that match a specified template are to be cached. You can use multiple occurrences of this directive in the configuration file. Include a separate directive for each template. The URL template must include the protocol. If no value is set for this directive, any URLs that do not match a NoCaching directive can be cached. If neither the CacheOnly nor the NoCaching directive is included in the configuration file, any URL can be cached.

Format

CacheOnly  url_pattern

Example

CacheOnly http://realstuff/*

Default

None

CacheQueries -- Specify cache responses to URLs containing a question mark (?)

Use this directive to specify the URLs for which responses to query requests are cached. If the value PUBLIC url_pattern is used, responses to GET requests that contain a question mark in the URL are cached if the origin server includes the cache-control: public header and the response is otherwise cacheable. If the value ALWAYS url_pattern is specified, responses to GET requests that contain a question mark in the URL are cached if the responses are otherwise cacheable.

This directive can be specified multiple times.

CacheQueries {ALWAYS | PUBLIC} url_pattern

Examples

CacheQueries ALWAYS http://www.hosta.com/*
CacheQueries PUBLIC http://www.hostb.com/* 
Note:
For backward compatibility, the previous syntax of CacheQueries {ALWAYS | PUBLIC | NEVER} is treated as follows:

Default

None

CacheRefreshInterval -- Specify the time interval for revalidating cached objects

Use this directive to specify when to check with the origin server to determine whether a cached file is changed.

Although the CacheClean directive appears to be similar to this directive, there is a difference. CacheRefreshInterval specifies only that the proxy revalidates a file before using it, whereas the CacheClean directive causes the file to be removed from the cache after a specified period of time.

Format

Examples

CacheRefreshInterval *.gif 8 hours
CacheRefreshInterval 1 week

Default

CacheRefreshInterval 2 weeks

CacheRefreshTime -- Specify when to start the cache agent

Use this directive to specify when to start the cache agent. You can start the cache agent at a specific time.

Format

CacheRefreshTime HH:MM

Default

CacheRefreshTime 03:00

CacheTimeMargin -- Specify the minimum lifetime for caching a file

The CacheTimeMargin directive specifies the minimum lifetime of a file that is required in order for it to be cached.

Caching Proxy computes an expiration time for each file. If it is unlikely that another request for the file will be received before the file expires, Caching Proxy considers the lifetime of the file to be too short for the file to be cached. By default, Caching Proxy does not cache files whose lifetime is less than 10 minutes. If your cache is not close to its maximum capacity, leave this directive at its initial value. If your cache is filled close to capacity, consider increasing the value for the minimum lifetime.

Format

CacheTimeMargin minimum_lifetime

Default

CacheTimeMargin 10 minutes
Note:
Setting this directive to more than four hours dramatically reduces the efficiency of the cache.

CacheUnused -- Specify how long to keep unused cached files

Use this directive to set the maximum length of time for the server to keep unused cached files with URLs that match a specified template. The server deletes unused files with URLs matching the template after they are cached for the specified time, regardless of their expiration date. You can include multiple occurrences of this directive in the configuration file. Include a separate directive for each template. The URL template must include the protocol. Specify the time value in any combination of months, weeks, days, and hours.

Format

CacheUnused url_template time_length

Examples

CacheUnused ftp:* 3 weeks
CacheUnused gopher:* 3 days 12 hours
CacheUnused * 4 weeks

Defaults

CacheUnused ftp:* 3 days
CacheUnused gopher:* 12 hours
CacheUnused http:* 2 days

Caching -- Enable proxy caching

Use this directive to enable the caching of files. With caching turned on, the proxy server stores the files it retrieves from other servers in a local cache. The proxy server then responds to subsequent requests for the same files without needing to retrieve them from other servers.

Format

Caching {on | off}

Default

Caching On
Note:
If you change the Caching directive, you must manually stop and then start the server. (See Starting and stopping Caching Proxy.)

CompressAge -- Specify when to compress logs

Use this directive to specify the age after which logs are compressed. When the logs are older than the value set for CompressAge, they are compressed. If CompressAge is set to 0, no logs are ever compressed. The logs for the current and previous days are never compressed.

Format

CompressAge number_of_days

Default

CompressAge 1

Related directives

CompressCommand -- Specify the compression command and parameters

Use this directive to build a command that identifies the compression utility used to compact the logs and that passes parameters to that utility. Include the path for the archived logs.

The compression utility must be installed in a directory listed in the path for that machine.

Format

CompressCommand command
command
Includes the command and parameters you want to use, entered on a single line. Typically, parameters include %%LOGFILES%% and %%DATE%%.
%%LOGFILES%%
Specifies the list of log files that are available for a particular %%DATE%%.
%%DATE%%
Specifies the date stamp on a log file.

Examples

Default

None

Related directives

CompressDeleteAge -- Specify when to delete logs

Use this directive to specify when to delete a log after it has been compressed. When a log is older than the number of days set for the value of CompressDeleteAge, it is deleted. If CompressDeleteAge is set to 0, or if its value is less than the value set for the CompressAge directive, a log is not deleted.

Note:
The compression plugin never deletes logs for the current day or the preceding day.

Format

CompressDeleteAge number_of_days

Default

CompressDeleteAge 7

Related directives

CompressionFilterAddContentType -- Specify the content type of HTTP response you want to compress

Use this directive to specify the content type of HTTP response that you want to compress.

Compressing the HTTP response helps reduce the network load and improves the proxy server performance. When the compression filter function is enabled, if the browser supports HTTP compression and if the HTTP response is not currently compressed, Caching Proxy compresses the HTTP response and returns the compressed content to the browser.

Examples

You can enable the compression filter function by adding the following two directives in the ibmproxy.conf file:

The mod_z library referenced in the CompressionFilterEnable directive is the dynamic version of zlib1.1.4.

The variable type-n is any valid value for the Content-Type header; for example: text/html or image/bmp.

Note:
The content of certain types of HTTP responses, for example JPEG images or video streams, are already highly compressed by applications; therefore, these should not be compressed using this function.

Default

None

CompressionFilterEnable -- Enable the compression filter to compress the HTTP responses

Use this directive to enable the compression filter to compress the HTTP responses either from the backend server or from the proxy server's cache.

For examples on how to use this directive, see CompressionFilterAddContentType -- Specify the content type of HTTP response you want to compress.

Default

None

ConfigFile -- Specify the name of an additional configuration file

Use this directive to specify the name and location of an additional configuration file. Directives found in the specified configuration file are processed after the current configuration file.

Note:
Ensure that the additional configuration file has its permission set to Read for user nobody to allow the cache agent to read this file.

Examples

Default

None

ConnThreads -- Specify the number of connection threads to be used for connection management

Use this directive to defines the number of connection threads to be used for connection management.

Format

ConnThreads number

Default

ConnThreads 5

Related directives

ContinueCaching -- Specify how much of a file is required for caching

Use this directive to specify how much of a requested file must be transferred for the Caching Proxy to complete the creation of the cache file, even though the client connection is terminated. Valid values for this variable are integers in the range of 0 - 100.

For example, if ContinueCaching 75 is specified, the Caching Proxy continues transferring the file from the content server and generates the cache file if 75% or more of the file is already transferred before the Caching Proxy detects that the client connection is terminated.

Format

ContinueCaching percentage

Default

ContinueCaching 75 

DefinePicsRule -- Supply a content-filtering rule

Use this directive to supply the proxy with the necessary information to filter URLs for content including rating service information. You can specify this directive multiple times.

Format

DefinePicsRule "filter_name"  {

Default

DefinePicsRule "RSAC Example" {

DefProt -- Specify default protection setup for requests that match a template

Use this directive to associate a default protection setup with requests that match a template.

Note:
For protection to work properly, the DefProt and Protect directives must be placed before any Pass or Exec directives in the configuration file.

Format

DefProt request_template  setup_name [FOR server_IP_address | host_name]
request_template
Specifies a template for requests that you want to associate with a default protection setup. The server compares incoming client requests to the template and associates a protection setup if there is a match.

Protection is not actually activated for requests matching the template unless the request also matches a template on a subsequent Protect directive. See Protect -- Activate a protection setup for requests that match a template for an explanation of how the Protect directive is used with DefProt.

setup
The named protection setup that is defined in the configuration file and that you want to associate with requests that match request_template. The protection setup is defined with protection subdirectives. This parameter can take one of three forms:
[FOR Server_IP_address | host_name]
If you are using multiple IP addresses or virtual hosts, use this parameter to specify an IP address or host name. The server uses the directive only for requests that come to the server on this IP address or for this host. For an IP address, this is the address of the server’s network connection, not the address of the requesting client.

You can specify an IP address (for example, FOR 240.146.167.72) or you can specify a host name (for example, FOR hostA.bcd.com).

This parameter is optional. Without this parameter, the server uses the directive for all requests regardless of the IP address on which the requests come in or the host name in the URL.

Notes:
  1. You can use this parameter only with the setup parameter specified in the form of a path and file name or a protection setup label. You cannot use this parameter with the setup parameter specified in the form of actual protection subdirectives enclosed in braces.
  2. To use this parameter, you must put FOR, or some other character string (without blanks), between the setup parameter and the IP_address or host_name.

A wildcard character cannot be specified for a server's IP address.

Note:
The directive must be typed on one line.

Examples

Default

None

DelayPeriod -- Specify pausing between requests

Use this directive to specify whether the cache agent waits between sending requests to destination servers. Specifying a delay between requests reduces the load on the proxy machine and your network link, as well as on the destination servers. Specifying no delay lets the cache agent run at maximum speed. For slow Internet connections, consider specifying no delay period in order to achieve maximum use of your network.

Note:
If your connection to the Internet is faster than 128 kbps, set DelayPeriod to On to avoid sending too many requests too rapidly to sites being refreshed.

Format

DelayPeriod {on | off}

Default

DelayPeriod On

DelveAcrossHosts -- Specify caching across domains

Use this directive to specify whether the cache agent follows hypertext links across hosts. If a cached URL contains links to other servers, the server can ignore the link or follow it. If the directive DelveInto is set to never, this directive is not applied.

Format

DelveAcrossHosts {on | off}

Default

DelveAcrossHosts Off

DelveDepth -- Specify how far to follow links while caching

Use this directive to specify the number of link levels to follow when searching for pages to load into the cache. If the directive DelveInto is set to never, this directive is not applied.

Format

DelveDepth number_of_levels

Default

DelveDepth 2

DelveInto -- Specify whether the cache agent follows links

Use this directive to specify whether the cache agent loads pages linked from cached URLs.

Format

DelveInto {always | never | admin | topn}
always
The cache agent follows links from all previously cached URLs.
never
The cache agent ignores all links on URLs.
admin
The cache agent follows links only on URLs specified in the LoadURL directives
topn
The cache agent follows links only from the most-frequently retrieved files in the cache.

Default

DelveInto always

DirBackgroundImage -- Specify a background image to directory listings

Use this directive to apply a background image to directory listings generated by the proxy server. Directory listings are generated when the proxy server is used to browse FTP sites.

Specify an absolute path for the background image. If the image is located on another server, the background image must be specified as a full URL. If no background image is specified, a plain white background is used.

Format

DirBackgroundImage /path/file

Examples

DirBackgroundImage /images/corplogo.png
DirBackgroundimage http://www.somehost.com/graphics/embossed.gif

Default

None

DirShowBytes -- Show byte count for small files on directory listings

Use this directive to specify whether directory listings include the exact byte count for files smaller than 1 KB. A value of Off means the directory listing shows a size of 1 KB for all files that are 1 KB or smaller.

Format

DirShowBytes {on | off}

Default

DirShowBytes Off

DirShowCase -- Use case when sorting files on directory listings

Use this directive to specify whether directory listings distinguish between uppercase and lowercase letters when sorting file names.

A value of On means that uppercase letters are placed before lowercase letters in the list of files.

Format

DirShowCase {on | off}

Default

DirShowCase On

DirShowDate -- Show the date of last modification on directory listings

Use this directive to specify whether directory listings include the date each file was last modified.

Format

DirShowDate {on | off}

Default

DirShowDate On

DirShowDescription -- Show descriptions for files on directory listings

Use this directive to specify whether directory listings include descriptions for HTML files. The descriptions are taken from the files’ HTML <title> tags.

Descriptions for FTP directory listings show the MIME types for files if they can be determined.

Format

DirShowDescription {on | off}

Default

DirShowDescription On

DirShowHidden -- Show hidden files on directory listings

Use this directive to specify whether directory listings include any hidden files in the directory. The server considers any file that has a name beginning with a period (.) to be a hidden file.

Format

DirShowHidden {on | off}

Default

DirShowHidden On

DirShowIcons -- Show icons in directory listings

Use this directive to specify whether the server includes icons in directory listings. Icons can be used to provide a graphic representation of the content type of the files in the listing. The icons themselves are defined by the AddBlankIcon, AddDirIcon, AddIcon, AddParentIcon, and AddUnknownIcon directives.

Format

DirShowIcons {on | off}

Default

DirShowIcons On

DirShowMaxDescrLength -- Specify the maximum length for descriptions on directory listings

Use this directive to set the maximum number of characters to show in the description field on directory listings.

Format

DirShowMaxDescrLength number_of_characters

Default

DirShowMaxDescrLength 25

DirShowMaxLength -- Specify the maximum length for file names on directory listings

Use this directive to set the maximum number of characters that are used for file names on directory listings.

Format

DirShowMaxDescrLength number_of_characters

Default

DirShowMaxLength 25

DirShowMinLength -- Specify the minimum length for file names on directory listings

Use this directive to set the minimum number of characters that are always reserved for file names on directory listings. File names in the directory can exceed this number. However, file names cannot be longer than the number specified on the DirShowMaxLength directive.

Format

DirShowMinLength number_of_characters

Default

DirShowMinLength 15

DirShowSize -- Show the file size on directory listings

Use this directive to specify whether directory listings include the size of each file.

Format

DirShowSize {on | off}

Default

DirShowSize On

Disable -- Disable HTTP methods

Use this directive to specify which HTTP methods the server does not accept. For each method that the server is to reject, enter a separate Disable directive.

In the default configuration file, the GET, HEAD, OPTIONS, POST, and TRACE methods are enabled and all other supported HTTP methods are disabled. To disable a method that is currently enabled, delete it from the Enable directive and add it to the Disable directive.

Format

Disable method
Note:
The Configuration and Administration forms use the POST method to make updates to the server configuration. If you disable the POST method, you will not be able to use the Configuration and Administration forms.

Defaults

Disable   PUT
Disable   DELETE
Disable   CONNECT 

DisInheritEnv -- Specify the environment variables that are disinherited by CGI programs

Use this directive to specify which environment variables you do not want your CGI programs to inherit (other than the CGI environment variables that are specific to CGI processing).

By default, all environment variables are inherited by CGI programs. Use this directive to exclude individual environment variables from being inherited.

Format

DisInheritEnv environment_variable

Examples

DisInheritEnv PATH
DisInheritEnv LANG

In this example, all environment variables except PATH and LANG are inherited by CGI programs.

Default

None

DNS-Lookup -- Specify whether the server looks up client host names

Use this directive to specify whether the server looks up the host names of requesting clients.

Format

DNS-Lookup {on | off}

The value you use affects the following things about how your server works:

Default

DNS-Lookup   Off

Enable -- Enable HTTP methods

Use this directive to specify which HTTP methods the server accepts.

You can enable as many of the HTTP methods as you need. For each method the server is to accept, enter a separate Enable directive.

Format

Enable method

If no Service directive exists for a particular URL, you can use the Enable directive to perform customized programming for any HTTP method. The program you specify on this directive overrides the standard processing for that method.

Enable method /path/fileDLL:function_name

For information on the format and available options for the Enable CONNECT method, see Configuring SSL tunneling.

Defaults

Enable GET  
Enable HEAD
Enable POST
Enable TRACE
Enable OPTIONS

EnableTcpNodelay -- Enable TCP NODELAY socket option

Use this directive to enable the TCP NODELAY socket option.

The EnableTcpNodelay directive improves performance when small IP packets, such as an SSL handshake or a short HTTP response, are transmitted between Caching Proxy and the client. By default, the TCP NODELAY option is enabled for all sockets.

Format

EnableTcpNodelay {All | HTTP | HTTPS | None}

Default

EnableTcpNodelay  All

Error -- Customize the Error step

Use this directive to specify a customized application function that you want the server to call during the Error step. This code is executed to provide customized error routines when an error is encountered.

Format

Error  request_template /path/file:function_name
request_template
Specifies a template for requests that further determine whether your application function is called. The specification can include the protocol, domain, and host; it can be preceded by a slash (/), and it can use an asterisk (*) as a wildcard. For example, /front_page.html, http://www.ics.raleigh.ibm.com, /pub*, /*, and * are all valid.
/path/file
Specifies the fully qualified file name of the compiled program, including the extension.
function_name
Specifies the name of the application function within your program.

Example

Error  /index.html /ics/api/bin/icsext05.so:error_rtns

Default

None

ErrorLog -- Specify the file where server errors are logged

Use this directive to specify the path and file name where you want the server to log internal errors.

Note:
If you change the server defaults for the user ID, group ID, or log directory paths, create the new directories and update the permissions and ownership of the directories. To enable the server to write information to a user-defined log directory, set the permission for that directory as 755, and set the user-defined server user ID as the owner. For example, if you change the user ID of the server from the default to jdoe, and you change the default logs directory to server_root/account, then the server_root/account directory must have the permission 755 and be owned by jdoe.

If it is running, the server starts a new log file each day at midnight. Otherwise, the server starts a new log file the first time it is started on any day. When creating the file, the server uses the file name you specify and appends a date suffix. The date suffix is in the format Mmmddyyyy, where Mmm represents the first three letters of the month; dd represents the day of the month; and yyyy represents the year.

Format

ErrorLog  /path/logs_directory/file_name

Defaults

ErrorPage -- Specify a customized message for a particular error condition

Use this directive to specify the name of a file that is sent to the requesting client when the server encounters a particular error condition. The configuration file ibmproxy.conf provides ErrorPage directives that associate the error keywords with error message files.

To customize error messages, you can modify the ErrorPage directives to associate the error keywords with different files, or you can modify the provided error message files. For example, you can change a message to include more information about the cause of the problem and suggest possible solutions to fix it. For internal networks, you might provide a contact person for your users to call.

ErrorPage directives can be placed anywhere in the configuration file. When the error occurs, the file is processed according to the mapping rules defined in your configuration file. Therefore, the file you want to send must be in a location that can be reached through the mapping rules as defined by the Fail, Map, NameTrans, Pass, Redirect, and Service directives. At a minimum, you need a Pass directive that allows the server to pass the error message file.

Format

ErrorPage keyword /path/filename.html
keyword
Specifies one of the keywords associated with an error condition. Keywords are listed in the ErrorPage directives in the file ibmproxy.conf. You cannot change the keywords.
/path/filename.html
Specifies the fully qualified Web name of your error file, as viewed by a client on the Web. Default error message files are in /HTML/errorpages/.

Example

ErrorPage scriptstart /HTML/errorpages/scriptstart.htmls

In this example, when a scriptstart condition is encountered, the server sends the scriptstart.htmls file found in the /HTML/errorpages/ directory to the client.

The following HTML text is an example what the file might contain:

<HTML>
<HEAD>
<TITLE>Message for SCRIPTSTART condition</TITLE>
</HEAD>
<BODY>
The CGI program could not be started.
<P>
<A HREF="mailto:admin@websvr.com">Notify the administrator</A>
of this problem.
</BODY>
</HTML>

If the directive that matches the above path in the server's configuration file is PASS /* /wwwhome/*, then the full path for this message file is /wwwhome/HTML/errorpages/scriptstart.htmls.

Customizing the error messages that the server returns

Each error condition is identified by a keyword. To decide which error messages you want to customize, first review the error message files provided with the Caching Proxy, which you can find in /HTML/errorpages. The error page includes the error number, the default message, an explanation of the cause, and an appropriate recovery action.

Then, do one of the following to change an error message:

Error conditions, causes, and default messages

All error keywords and default error message files are listed in the file ibmproxy.conf in the ErrorPage directive section. The error message files include the error message number, keyword, default message, explanation, and user response (action).

Defaults

Numerous defaults are included in the file ibmproxy.conf

If you do not modify an ErrorPage directive for an error condition, the server's default error page for that condition is sent.

EventLog -- Specify the path for the event log file

Use this directive to specify the event log path and file name. The event log captures informational messages about the cache itself.

Note:
If you change the server defaults for the user ID, group ID, or log directory paths, create the new directories and update the permissions and ownership of the directories. To enable the server to write information to a user-defined log directory, set the permission for that directory as 755, and set the user-defined server user ID as the owner. For example, if you change the user ID of the server from the default to jdoe and you change the default logs directory to server_root/account, then the server_root/account directory must have the permission 755 and be owned by jdoe.

If it is running, the server starts a new log file each day at midnight . Otherwise, the server starts a new log file the first time it is started on any day. When creating the file, the server uses the file name you specify and appends a date suffix. The date suffix is in the format Mmmddyyyy, where Mmm represents the first three letters of the month; dd represents the day of the month; and yyyy represents the year.

Format

EventLog  /path/logs_directory/file_name

Defaults

Exec -- Run a CGI program for matching requests

Use this directive to specify a template for requests to accept and respond to by running a CGI program. After a request matches a template on an Exec directive, the request is not compared to request templates on any subsequent directives.

Format

Exec  request_template program_path [Server_IP_address | host_name]
request_template
Specifies a template for requests that the server is to accept and respond to by running a CGI program.

You must use an asterisk (*) as a wildcard in both the request_template and program_path. The part of the request that matches the request_template wildcard must begin with the name of the file that contains the CGI program.

The request can also contain additional data that is passed to the CGI program in the PATH_INFO environment variable. The additional data follows the first slash character (/) that comes after the CGI program file name on the request. The data is passed according to CGI specifications.

program_path
Specifies the path to the file that contains the CGI program that the server executes for the request. program_path must also contain a wildcard. The wildcard is replaced with the name of the file that contains the CGI program.

The Exec directive is recursive and applies to all subdirectories. You do not need a separate Exec directive for each directory under cgi-bin and admin-bin.

[Server_IP_address | host_name]
If you are using multiple IP addresses or virtual hosts, use this parameter to specify an IP address or a host name. The server uses the directive only for requests that come to the server on this IP address or for this host. For an IP address, this is the address of the server’s network connection, not the address of the requesting client.

You can specify an IP address (for example, 240.146.167.72) or you can specify a host name (for example, hostA.bcd.com).

This parameter is optional. Without this parameter, the server uses the directive for all requests regardless of the IP address the requests come in on or the host name in the URL.

Wildcard characters cannot be used to specify server IP addresses.

Examples

In the following example, if the server receives a request of /idd/depts/plan/c92, it runs the CGI program in /depts/bin/plan.exe with c92 passed to the program as input.

The following example uses the optional IP address parameter. If your server receives requests that begin with /cgi-bin/, it serves the request from a different directory based on the IP address of the network connection on which the request comes in. For requests coming in on 130.146.167.72, the server uses the /CGI-BIN/customerA directory. For requests coming in on any connection with an address of 0.83.100.45, the server uses the /CGI-BIN/customerB directory.

Exec    /cgi-bin/*    /CGI-BIN/customerA/*   130.129.167.72
Exec    /cgi-bin/*    /CGI-BIN/customerB/*   0.83.100.45

The following example uses the optional host name parameter. If your server receives requests that begin with /cgi-bin, it serves the request from a different directory based on the host name in the URL. For requests coming in for hostA.bcd.com, the server uses the /CGI-BIN/customerA directory. For requests coming in for hostB.bcd.com, the server uses the /CGI-BIN/customerB directory.

Exec    /cgi-bin/*    /CGI-BIN/customerA/*   hostA.bcd.com
Exec    /cgi-bin/*    /CGI-BIN/customerB/*   hostB.bcd.com

Defaults

ExportCacheImageTo -- Export cache memory to disk

Use this directive to export the cache contents to a dump file. This is useful when memory cache gets lost during restart, or when deploying the same cache for multiple proxies.

Format

ExportCacheImageTo export_file_name

Default

None

ExternalCacheManager -- Configure the Caching Proxy for dynamic caching from IBM WebSphere Application Server

This applies to reverse proxy configurations only.

Use this directive to configure the Caching Proxy to recognize a IBM® WebSphere® Application Server (that is configured with a Caching Proxy adapter module) from which it can cache dynamically created resources. The Caching Proxy saves copies of JSP results that also are stored in the application server's dynamic cache. The Caching Proxy caches only contents from a IBM WebSphere Application Server whose group ID matches an ExternalCacheManager entry.

Note that it is also necessary to add a Service directive to the Caching Proxy configuration file to enable this feature. Additional configuration steps also are necessary at the application server. Refer to Caching dynamically generated content for complete information.

Format

ExternalCacheManager External_Cache_Manager_ID  Maximum_Expiry_Time  
External_Cache_Manager_ID
The ID assigned to the IBM WebSphere Application Server that is serving the proxy. The ID must match the ID set in the externalCacheGroup: group id attribute in the dynacache.xml file on the application server.
Maximum_Expiry_Time
The default expiration time set for resources cached on behalf of the external cache manager. If the external cache manager does not invalidate a cached resource within the specified time, the resource expires in the specified time. The time can be specified in minutes or seconds.

Example

The following entry defines an external cache manager (a IBM WebSphere Application Server) that is within the www.xyz.com domain and whose resources expire in 20 seconds or earlier.

ExternalCacheManager   IBM-CP-XYZ-1  20 seconds

Default

None

Fail -- Reject matching requests

Use this directive to specify a template for requests that the server is not to process. After a request matches a template on a Fail directive, the request is not compared to request templates on any subsequent directives.

Format

Fail request_template [Server_IP_address | host_name]
request_template
Specifies a template for requests that the server is to reject. If a request matches the template, the server sends the requester an error message.

You can use an asterisk as a wildcard in the template. The tilde character (~) just after a slash (/) must be explicitly matched; a wildcard cannot be used to match it.

[Server_IP_address | host_name]
If you are using multiple IP addresses or virtual hosts, use this parameter to specify an IP address or a host name. The server uses the directive only for requests that come to the server on this IP address or for this host. For an IP address, this is the address of the server’s network connection, not the address of the requesting client.

You can specify an IP address (for example, 240.146.167.72) or you can specify a host name (for example, hostA.bcd.com).

This parameter is optional. Without this parameter, the server uses the directive for all requests regardless of the IP address the requests come in on or the host name in the URL.

A wildcard character cannot be specified for a server's IP address.

Examples

In the following example, the server rejects any requests beginning with /usr/local/private/.

Fail /usr/local/private/*

The following examples use the optional IP address parameter. The server rejects any requests beginning with /customerB/ if the request comes in on a network connection with the IP address 240.146.167.72. The server rejects any requests beginning with /customerA/ if the request comes in on a network connection with the IP address 0.83.100.45.

Fail    /customerB/*    240.146.167.72
Fail    /customerA/*    0.83.100.45

The following examples use the optional host name parameter. The server rejects any requests beginning with /customerB/ if the request comes in for hostA.bcd.com. The server rejects any requests beginning with /customerA/ if the request comes in for hostB.bcd.com.

Fail    /customerB/*    hostA.bcd.com
Fail    /customerA/*    hostB.bcd.com

Default

None

FIPSEnable -- Enable Federal Information Processing Standard (FIPS) approved ciphers for SSLV3 and TLS

Use this directive to enable FIPS approved ciphers for SSLV3 and TLS protocol in SSL connections. When this directive is enabled, the list of supported cipher specifications for SSLV3 (V3CipherSpecs directive) is ignored. Also, the allowed TLS cipher specifications will be set to 352F0AFF09FE, and the SSLV3 cipher specifications will be set to FFFE.

Format

FIPSEnable {on | off}

Default

FIPSEnable  off

flexibleSocks -- Enable flexible SOCKS implementation

Use this directive to instruct the proxy to use the SOCKS configuration file to determine the type of connection to make.

Format

flexibleSocks {on | off}

Default

flexibleSocks on

FTPDirInfo -- Generate a welcome or description message for a directory

Use this directive to enable FTP servers to generate a welcome or descriptive message for a directory. This message can optionally be displayed as part of the FTP listings. The FTPDirInfo directive allows you to control where the message is displayed.

Format

FTPDirInfo  {top | bottom | off} 
top
Display the welcome message at the top of the page, before the listing of files in the directory.
bottom
Display the welcome message at the bottom of the page, after the listing of files in the directory.
off
Do not display the welcome page.

Default

FTPDirInfo top

ftp_proxy -- Specify another proxy server for FTP requests

If your proxy server is part of a chain of proxies, use this directive to specify the name of another proxy that this server contacts for FTP requests. You must specify a full URL, including the trailing slash character (/). For information on using an optional domain name or template, refer tono_proxy -- Specify templates for connecting directly to domains.

This applies to forward proxy configurations only.

Format

ftp_proxy full_URL [domain_name_or_template]

Example

ftp_proxy http:// outer.proxy.server/

Default

None

FTPUrlPath -- Specify how FTP URLs are interpreted

Use this directive to specify whether the path information in FTP URLs is interpreted as relative to the logged-in user's working directory or to the root directory.

Format

FTPUrlPath  {relative | absolute} 

If the FTPUrlPath directive is set to absolute, then the logged-in user's FTP working directory must be included in the FTP URL path. If FTPUrlPath Relative is specified, then the logged-in user's FTP working directory must be omitted from the FTP URL path. For example, to access the file test1.html, contained in the working directory /export/home/user1 for a logged-in user, the following URL paths are required, depending on the setting of the FTPUrlPath directive:

Default

None

Gc -- Specify garbage collection

Use this directive to specify whether garbage collection is used. If caching is enabled, the server uses the garbage collection process to delete files that must no longer be cached. Files are deleted based on their expiration date and other proxy directive values. Generally, if caching is enabled, garbage collecting is used. If garbage collection is not used, the proxy cache is used inefficiently.

Format

Gc {on | off}

Default

Gc On

GCAdvisor -- Customize the garbage collection process

Use this directive to specify a customized application you want the server to use for garbage collection.

Format

GCAdvisor /path/file:function_name
/path/file
Specifies the fully qualified file name of the compiled program, including the extension.
function_name
Specifies the name of the application function within your program.

Example

GCAdvisor /api/bin/customadvise.so:gcadv

GcHighWater -- Specify when garbage collection begins

Use this directive to specify the percentage of the total cache capacity that must be filled to trigger garbage collection. This percentage is called the high-water mark. The high-water mark is specified as a percentage of the total cache capacity. Garbage collection continues until the low-water mark has been reached--see GcLowWater -- Specify when garbage collection ends for information about setting this. The percentage for the high-water mark can be set between 50 and 95.

Format

GcHighWater percentage

Default

GcHighWater 90 

GcLowWater -- Specify when garbage collection ends

Use this directive to specify the percentage of the total cache capacity that triggers the end of garbage collection. This percentage is known as the low-water mark. The low-water mark is specified as a percentage of the total cache capacity. It must be set to a value lower than the value set for the high-water mark; see GcHighWater -- Specify when garbage collection begins for information about setting the high-water mark.

Format

GcLowWater percentage

Default

GcLowWater 60

gopher_proxy -- Specify another proxy server for Gopher requests

If the proxy server is part of a chain of proxies, use this directive to specify the name of another proxy that this server contacts for Gopher requests. You must specify a full URL including the trailing slash (/). For information on using an optional domain name or template, refer tono_proxy -- Specify templates for connecting directly to domains.

This applies to forward proxy configurations only.

Format

gopher_proxy full_URL[domain_name_or_template]

Example

gopher_proxy http://outer.proxy.server/

Default

None

GroupId -- Specify the group ID

Use this directive to specify the group name or number to which the server changes before accessing files.

If you change this directive, you must manually stop and then start your server again in order for the change to take effect. The change does not take effect if you only restart the server. (See Starting and stopping Caching Proxy.)

Note:
If you change the server defaults for the user ID, group ID, or log directory paths, create the new directories and update the permissions and ownership of the directories. To enable the server to write information to a user-defined log directory, set the permission for that directory as 755 and the set the user-defined server user ID as the owner. For example, if you change the user ID of the server from the default to jdoe, and the default logs directory to server_root/account, then the server_root/account directory must have the permission 755 and be owned by jdoe.

Format

GroupId { group_name | group_number} 

Defaults

AIX: GroupId nobody

HP-UX: GroupId other

Linux:

Solaris: GroupId nobody

HeaderServerName -- Specify the name of the proxy server returned in the HTTP header

Use this directive to specify the name of the proxy server returned in the HTTP header

Format

HeaderServerName name

Default

None

Hostname -- Specify the fully qualified domain name or IP address for the server

Use this directive to specify the domain name or an IP address returned to clients from file requests. If you specify a domain name, a domain name server must be able to resolve the name into an IP address. If you specify an IP address, the domain name server is not needed or accessed.

Note:
When an array is set up, the Hostname directive must be configured identically on all members of that array.

Format

Hostname {name | IP address}

Default

By default, this directive is not specified in the initial configuration file. If you do not specify this directive in the configuration file, the value defaults to the host name defined in your domain name server.

http_proxy -- Specify another proxy server for HTTP requests

If the proxy server is part of a chain of proxies, use this directive to specify the name of another proxy that this server contacts for HTTP requests. You must specify a full URL, including the trailing slash (/). For information on using an optional domain name or template, refer tono_proxy -- Specify templates for connecting directly to domains.

Format

http_proxy full_URL[domain_name_or_template]

Example

http://outer.proxy.server/

Default

None

HTTPSCheckRoot -- Filter HTTPS requests

Use this directive to specify whether the Caching Proxy retrieves the insecure home page for the URL and attempts to find labels in it. If labels are found, they are applied to the secure request. For example, if you request https://www.ibm.com/, the Caching Proxy retrieves http://www.ibm.com/, searches it for labels, and uses any labels it finds to filter https://www.ibm.com/.

If HTTPSCheckRoot is set to off, the Caching Proxy does not retrieve the insecure home page and search it for labels.

Format

HTTPSCheckRoot {on | off}

Default

HTTPSCheckRoot  on

ICP_Address -- Specify IP address for ICP queries

Use this subdirective to specify an IP address that is used for sending and receiving ICP queries. It must be enclosed within the <MODULEBEGIN> ICP and <MODULEEND> directives.

Format

ICP_Address IP_address

Default

By default, this directive is not specified in the initial configuration file. If you do not specify this directive in the configuration file, the value defaults to accepting and sending ICP queries on any interface.

ICP_MaxThreads -- Specify maximum threads for ICP queries

Use this subdirective to specify the number of threads spawned to listen for ICP queries. It must be enclosed within the <MODULEBEGIN> ICP and <MODULEEND> directives.

Note:
On Redhat Linux 6.2 and lower, this number must be low because the maximum number of threads that can be created per process is small. Specifying a large number threads for ICP use might limit the number of threads available for use in servicing requests.

Format

ICP_MaxThreads number_of_threads

Default

ICP_MaxThreads   5

Occupier -- Specify a member of an ICP cluster

If the proxy server is part of an ICP cluster, use this subdirective to specify the ICP peers. It must be enclosed within the <MODULEBEGIN> ICP and <MODULEEND> directives.

When a new peer is added to the ICP cluster, ICP peer information must be added to the configuration file of all existing peers. Use one line for each peer. Note that the current host can also be included in the peer list. When ICP initializes, it ignores the current host's entry. This makes it possible to have a single configuration file that can be copied to other peer machines without editing it to remove the current host.

Format

ICP_Peer hostname http_port icp_port
hostname
The name of the peer
http_port
The peer's proxy port
icp_port
The peer's ICP server port

Example

The following line adds the host abc.xcompany.com, whose proxy port is 80 and ICP port 3128, as a peer.

ICP_Peer  abc.xcompany.com  80  3128

Default

None

ICP_Port -- Specify port number for ICP queries

Use this subdirective to specify the port number on which the ICP server listens for ICP queries. It must be enclosed within the <MODULEBEGIN> ICP and <MODULEEND> directives.

Format

ICP_Port port_number

Default

ICP_Port 3128

ICP_Timeout -- Specify maximum wait time for ICP queries

Use this subdirective to specify the maximum time that Caching Proxy waits for responses to ICP queries. The time is specified in milliseconds. It must be enclosed within the <MODULEBEGIN> ICP and <MODULEEND> directives.

Format

ICP_Timeout  timeout_in_milliseconds

Default

ICP_Timeout  2000

IgnoreURL -- Specify URLs that are not refreshed

Use this directive to specify URLs that are not to be loaded by the cache agent. This directive is useful when the cache agent is loading pages linked from cached URLs. You can use multiple occurrences of the IgnoreURL directive to specify different URLs or URL masks. The value for this directive can contain asterisks (*) as wildcards, to apply a mask.

Format

IgnoreURL URL

Examples

IgnoreURL http://www.yahoo.com/
IgnoreURL http://*.ibm.com/*

Default

IgnoreURL */cgi-bin/* 

imbeds -- Specify whether server-side include processing is used

Use this directive to specify whether you want server-side include processing to be performed for files served from the file system, CGI programs, or both. Server-side include processing is done on files with a content type of ext/x-ssi-html. Optionally, you can specify that server-side include processing is also done for files with a content type of text/html. For more information about content types, see AddType -- Specify the data type of files with particular suffixes.

You can use server-side include processing to dynamically insert information into the file being returned. Such information can include the date, the size of a file, the last change date of a file, CGI or server-side include environment variables, or text files. Server-side include processing is performed only on files originated locally. The Caching Proxy does not perform server-side include processing on proxied or cached objects.

Server-side include processing causes the server to search your files for special commands each time they are served. This can affect the server's performance and slow down response time to clients.

Format

imbeds {on | off | files | cgi | noexec}  {SSIOnly | html}
on
Server-side include processing is done for files from the file system and from CGI programs.
off
Server-side include processing is not done for any files.
files
Server-side include processing is done only for files from the file system.
cgi
Server-side include processing is done only for files returned by CGI programs.
noexec
SSIOnly
Server-side include processing is done for files with a content type of text/x-ssi-html.
html
Server-side include processing is done for files with a content type of text/html and a content type of text/x-ssi-html.

The server checks the content type of each file it retrieves and the output of each CGI program it processes.

Server-side include processing is normally done only for files having a content type of text/x-ssi/html. However, you can specify that files with a content type of text/html are processed for server-side includes.

Note:
The server treats html, .html, and .htm as html. Anything else is treated as SSIOnly.

Each suffix must have an AddType directive defined with the correct content type. If you use suffixes other than .htm or .html, make sure an AddType directive is defined with a content type of text/x-ssi/html.

Default

imbeds on SSIOnly

ImportCacheImageFrom -- Import cache memory from a file

Use this directive to import the cache contents from a dump file. This is useful when memory cache gets lost during restart, or when deploying the same cache for multiple proxies.

Format

ImportCacheImageFrom import_file_name

Default

None

InheritEnv -- Specify which environment variables are inherited by CGI programs

Use this directive to specify which environment variables you want your CGI programs to inherit (other than the CGI environment variables that are specific to CGI processing).

If you do not include an InheritEnv directive, all environment variables are inherited by CGI programs. If you include any InheritEnv directive, only those environment variables specified on InheritEnv directives are inherited along with the CGI-specific environment variables. The directive allows you to optionally initialize the value of the variables that are inherited.

Format

InheritEnv environment_variable

Examples

InheritEnv PATH
InheritEnv LANG=ENUS

In this example, only the PATH and LANG environment variables are inherited by CGI programs, and the LANG environment variable is initialized with the value of ENUS.

Default

None. By default, all environment variables are inherited by CGI programs.

InputTimeout -- Specify the input timeout

Use this directive to set the time allowed for a client to send a request after making a connection to the server. A client first connects to the server and then sends a request. If the client does not send a request within the amount of time specified with this directive, the server closes the connection. Specify the time value in any combination of hours, minutes (or mins), and seconds (or secs).

Format

InputTimeout time

Example

InputTimeout 3 mins 30 secs

Default

InputTimeout 2 minutes

JunctionReplaceUrlPrefix -- Replace URL instead of insert prefix when used with JunctionRewrite plugin

This directive will override the default action of the JunctionRewrite plugin, allowing the proxy to correct certain URL links in the html page. It is used in conjunction with the JunctionRewrite directive.

This applies to reverse proxy configurations only.

The JunctionReplaceUrlPrefix directive will direct the JunctionRewrite plugin to replace the URL from url_pattern_1 to url_pattern_2, instead of inserting a prefix at the beginning of the URL.

Format

JunctionReplaceUrlPrefix url_pattern_1 url_pattern_2

Example

JunctionReplaceUrlPrefix /server1.internaldomain.com/*  /server1/*     

In this example, assume the URL is /server1.internaldomain.com/notes.nsf and assume the prefix is /server1. Instead of inserting the prefix to rewrite the URL to /server1/server1.internaldomain.com/notes.nsf, the JunctionRewrite plugin will change the URL to /server1/notes.nsf.

Default

None

JunctionRewrite -- Enables URL rewriting

This directive enables the junction rewriting routine within the Caching Proxy to rewrite responses from origin servers to ensure that server relative URLs get mapped to the appropriate origin server when junctions are used.

This applies to reverse proxy configurations only.

The junction rewriting plugin must also be enabled if you set JunctionRewrite on without the UseCookie option. Junctions are defined by the proxy mapping rules.

See UseCookie as an alternative to JunctionRewrite and Sample transmogrifier plugin to extend JunctionRewrite functionality for additional information about JunctionRewrite.

Format

JunctionRewrite {on | on UseCookie | off}

Default

JunctionRewrite off

JunctionRewriteSetCookiePath -- Rewrite the path option in the Set-Cookie header, when used with JunctionRewrite plugin

The directive will allow the proxy to rewrite the path option in the Set-Cookie header when the cookie name is matched. If the response needs junction, and a junction prefix is defined, the prefix will be inserted before each path. It can be used with the JunctionRewrite plugin, or it can be used with the RewriteSetCookieDomain directive.

This applies to reverse proxy configurations only.

Format

JunctionRewriteSetCookiePath cookie-name1 cookie-name2...  
cookie-name
A cookie name in the Set-Cookie header.

Default

None

JunctionSkipUrlPrefix -- Skip rewriting URLs that already contain the prefix, when used with JunctionRewrite plugin

This directive will override the default action of the JunctionRewrite plugin, skipping the URL rewrite if the URL-pattern already matches. It works with the JunctionRewrite plugin providing a way to correct some of the URL links in the html page. Normally, the directive is used to skip the URLs that already include a prefix.

This applies to reverse proxy configurations only.

Format

JunctionSkipUrlPrefix url_pattern 

Example

JunctionSkipUrlPrefix  /server1/*     

In this example, assume the URL is /server1/notes.nsf and assume the junction prefix is /server1/. Instead of rewriting the URL to /server1/server1/notes.nsf, the JunctionRewrite plugin will skip rewriting the URL, and the URL remains unchanged as /server1/notes.nsf.

Default

None

KeepExpired -- Specify returning the expired copy of the resource if that resource is being updated on the proxy

Use this directive to help prevent flooding backend servers with requests while a cache object is being revalidated.

When a cache object is being revalidated with the content on the backend server, requests for the same resource will be proxied to the backend server. Sometimes the flood for the same requests will cause the backend server to go down. Enabling this directive can help prevent this situation from occurring. When the directive is enabled, an expired or staled copy of the resource will be returned if that resource is being updated on the proxy.

Format

KeepExpired {on | off}

Default

KeepExpired off

KeyRing -- Specify the file path to the key ring database

Use this directive to specify the file path to the key ring database that the server uses for SSL requests. Key ring files are generated via the iKeyman key manager utility.

Note:
The SSL directives are not supported on SUSE Linux.

Format

KeyRing filename

Examples

Windows: KeyRing c:\Program Files\IBM\edge\cp\\key.kdb

Linux and UNIX: KeyRing /etc/key.kdb

Default

None

KeyRingStash -- Specify the file path to the key ring database's password file

Use this directive to to specify the file path to the key ring database's password file. The password file is generated via the iKeyman key manager utility when a key ring database file is built.

Note:
The SSL directives are not supported on SUSE Linux.

Format

KeyRingStash file_path

Examples

Windows: KeyRingStash c:\Program Files\IBM\edge\cp\key.sth

Linux and UNIX: KeyRingStash /etc/key.sth

Default

None

LimitRequestBody -- Specify the maximum body size in PUT or POST requests

Use this directive to control the maximum body size in PUT or POST requests. The LimitRequest directives are used to protect the proxy from attack.

The value can be specified in kilobytes (K), megabytes (M), or gigabytes (G).

Format

LimitRequestBody max_body_size {K | M | G}

Default

LimitRequestBody 10 M

LimitRequestFields -- Specify the maximum number of headers in client requests

Use this directive to specify the maximum number of headers that can be sent in client requests. The LimitRequest directives are used to protect the proxy from attack.

Format

LimitRequestFields number_headers 

Default

LimitRequestFields 32

LimitRequestFieldSize -- Specify the maximum header length and request line

Use this directive to specify the maximum length of the request line and the maximum length of each header in a request. The LimitRequest directives are used to protect the proxy from attack.

The value can be specified in bytes (B) or kilobytes (K).

Format

LimitRequestFieldSize max_hdr_length {B | K}

Default

LimitRequestFieldSize 4096 B

ListenBacklog -- Specify the number of listen backlog client connections that the server can carry

Use this directive to specify the number of listen backlog client connections that the server carries before it sends connection refused messages to clients. This number depends on the number of requests that your server can process in a few seconds. Do not set it to a value higher than the number the server can process before the clients time out and abort the connection.

Note:
If the ListenBacklog value is greater than the SOMAXCONN value supported by TCP/IP, the SOMAXCONN value is used instead.

Format

ListenBacklog number_of_requests

Default

ListenBacklog 128

LoadInlineImages -- Control the refreshing of imbedded images

Use this directive to specify whether inline images are retrieved by the cache agent. If LoadInlineImages is set to on, images that are imbedded in a page that is being cached are also cached. If it is set to off, imbedded images are not cached.

Format

LoadInlineImages {on | off}

Default

LoadInlineImages on

LoadTopCached -- Specify the number of popular pages to refresh

Use this directive to instruct the cache agent to access the previous night's cache access log and load the most-requested URLs.

The Caching directive must be set to On, and a value must be set for the CacheAccessLog directive when a value is set for the LoadTopCached directive.

Format

LoadTopCached number_of_pages

Default

LoadTopCached 100

LoadURL -- Specify the URLs to refresh

Use this directive to specify URLs to be loaded into the cache by the cache agent. Multiple LoadURL directives can be included in the configuration file, but wildcards cannot be used.

Format

LoadURL url

Example

LoadURL http://www.ibm.com/ 

Default

None

Log -- Customize the Log step

Use this directive to specify a customized application function that the server calls during the Log step. This code provides logging and other processing that is performed after the connection is closed.

Format

Log request_template /path/file:function_name
request_template
Specifies a template for requests that further determine whether your application function is called. The specification can include the protocol, domain and host; it can be preceded by a slash (/) and can use an asterisk (*) as a wildcard. For example, /front_page.html, http://www.ics.raleigh.ibm.com, /pub*, /*, and * are all valid.
/path/file
Specifies the fully qualified file name of the compiled program, including the extension.
function_name
Specifies the name of the application function within your program. You must supply the names of the open, write, and close functions.

Example

Log /index.html /api/bin/icsextpgm.so:log_url

Default

None

LogArchive -- Specify the behavior of log archiving

Use this directive to specify the behavior of the archiving routine. This directive affects all logs with global settings. It specifies that logs are compressed or purged, or that nothing is done with them.

If you specify Compress, use the CompressAge and CompressDeleteAge directives to specify when the logs are compressed or deleted. Use the CompressCommand directive to specify which command and its parameters to use.

If you specify Purge, use the PurgeAge and PurgeSize directives to specify when the logs are purged.

Format

   LogArchive {Compress | Purge | none}
Compress
Specifies that the archiving routine compresses the logs.
Purge
Specifies that the archiving routine erases the logs.
none
Specifies that the archiving routine does nothing.

Default

LogArchive Purge

Related directives

LogFileFormat -- Specify the access log format

Use this directive to specify the file format of the access log files.

Format

LogFileFormat  {common | combined}

By default, logs are displayed in the NCSA Common Log Format. Specify combined to display logs in NCSA Combined Log Format instead. The combined format adds fields for Referring URL, User Agent, and Cookie (if present in the request).

Default

LogFileFormat  common

LogToGUI (Windows only) -- Display log entries in the server window

Windows systems only. When running the proxy via the command line, use this directive to output to the access log. To optimize server performance, by default this directive is set to off (disabled).

Note:
This directive has no effect when running the proxy as a service.

Format

LogToGUI  {on | off}

Default

LogToGUI off

LogToSyslog -- Specify whether to send access information to the system log (Linux and UNIX only)

Linux and UNIX systems only. Use this directive to specify whether the server logs access requests and errors to the system log in addition to the access and error log files.

Format

LogToSyslog {on | off}

The system log file must be present on your server before you specify that error log information is written to it. You can choose whether to log access information, error information, or both.

To send only error information to the system log, add the following line to your /etc/syslog.conf file:

user.err syslog_output_file_for_error_information

To send only access information to the system log, add the following line to your /etc/syslog.conf file:

user.info syslog_info_file_for_access_information

To send both error and access information to the system log, add both of the lines to your /etc/syslog.conf file:

Specify syslog_output_file and syslog_info_file in the following formats:

After you create the system log file, you can restart it with the following command:

kill -HUP 'cat /etc/syslog.pid'

Default

LogToSyslog Off

Map -- Change matching requests to a new request string, using the request path string to match the rule

Use this directive to specify a template for requests that you want to change to a new request string. After the server changes the request, it takes the new request string and compares it to the request templates on subsequent directives.

The Map directive uses the incoming request path string to match the rule. See also MapQuery -- Change matching requests to a new request string, using the request path and query string to match the rule.

Format

Map request_template new_request [server_IP_address | host_name]
request_template
Specifies a template for requests that the server changes and then continues comparing the new request string to other templates.

You can use an asterisk (*)as a wildcard in the template. The tilde character (~) just after a slash (/) must be explicitly matched; a wildcard cannot be used to match it.

new_request
Specifies the new request string that the server continues to compare the request templates on subsequent directives. The string specified with new_request can contain a wildcard if the request_template has one. The part of the request that matches the request_template wildcard is inserted in place of the wildcard in new_request.
[server_IP_address | host_name]
If you are using multiple IP addresses or virtual hosts, use this parameter to specify an IP address or a host name. The server uses the directive only for requests that come to the server on this IP address or for this host. For an IP address, this is the address of the server’s network connection, not the address of the requesting client.

You can specify an IP address (for example, 240.146.167.72) or you can specify a host name (for example, hostA.raleigh.ibm.com).

This parameter is optional. Without this parameter, the server uses the directive for all requests regardless of the IP address the requests come in on or the host name in the URL.

A wildcard character cannot be specified for a server's IP address.

Examples

Default

None

MapQuery -- Change matching requests to a new request string, using the request path and query string to match the rule

Use this directive to specify a template for requests that you want to change to a new request string. After the server changes the request, it takes the new request string and compares it to the request templates on subsequent directives.

The functionality of the directive is almost the same as the Map rule (Map -- Change matching requests to a new request string, using the request path string to match the rule). However, in order to handle a URL with a query string, MapQuery uses both the path and query string to match the rule. If the incoming URL is matched on a MapQuery rule, the translated URL will be used to match against the rest of the rules.

MapQuery can also translate a URL with a query string to another URL with a different path or different query string. However, because all other mapping directives only use request path, the changed query string will only be appended (will not be used to match patterns) to the translated URL when the request path is matched.

Format

MapQuery request_template new_request [server_IP_address | host_name]
request_template
Specifies a template for requests that the server changes and then continues comparing the new request string to other templates.

You can use an asterisk (*)as a wildcard in the template. The tilde character (~) just after a slash (/) must be explicitly matched; a wildcard cannot be used to match it.

new_request
Specifies the new request string that the server continues to compare the request templates on subsequent directives. The string specified with new_request can contain a wildcard if the request_template has one. The part of the request that matches the request_template wildcard is inserted in place of the wildcard in new_request.
[server_IP_address | host_name]
If you are using multiple IP addresses or virtual hosts, use this parameter to specify an IP address or a host name. The server uses the directive only for requests that come to the server on this IP address or for this host. For an IP address, this is the address of the server’s network connection, not the address of the requesting client.

You can specify an IP address (for example, 240.146.167.72) or you can specify a host name (for example, hostA.raleigh.ibm.com).

This parameter is optional. Without this parameter, the server uses the directive for all requests regardless of the IP address the requests come in on or the host name in the URL.

A wildcard character cannot be specified for a server's IP address.

Examples

Assuming the incoming URL is the following,

/getsomthing?type=1

and the MapQuery rule is the following,

MapQuery  /getsomething?type=*  /gettype/*

The translated URL will be /gettype/1, and it will be used in the next rule mapping.

Proxy  /gettype/*  http://server/gettype/*

The translated URL will be http://server/gettype/1.

Default

None

MaxActiveThreads -- Specify the maximum number of active threads

Use this directive to set the maximum number of threads that are active at one time. If the maximum is reached, the server holds new requests until another request finishes and threads become available. Generally, the more power a machine has, the higher the value that is set for this directive. If a machine starts to spend too much time on overhead tasks, such as swapping memory, try reducing this value.

Format

MaxActiveThreads number_of_threads

Default

MaxActiveThreads 100

MaxContentLengthBuffer -- Specify the size of the buffer for dynamic data

Use this directive to set the size of the buffer for dynamic data generated by the server. Dynamic data is output from CGI programs, server-side includes, and API programs.

The value can be specified in bytes (B), kilobytes (K), megabytes (M), or gigabytes (G). It does not matter whether there is a space between the number and the value (B, K, M, G).

Format

MaxContentLengthBuffer size

Default

MaxContentLengthBuffer 100 K

MaxLogFileSize -- Specify the maximum size for each log file

Use this directive to specify the maximum size for each log file. Each log file cannot exceed the size defined by this directive. Once a log file reaches the maximum defined size, the current log file will be closed, and a new log file will be created with the same name, appended by the next incremental integer value.

Notes:
  1. Caching Proxy is a 32-bit application and opens its log files with a 32-bit function. Because of this constraint, do not specify a MaxLogFileSize greater than 2 GB. Caching Proxy may hang if the log file exceeds 2 GB in size when Caching Proxy attempts to write to the log file while still actively processing requests.
  2. On Linux and UNIX platforms, the log files will not be created if the permissions of the directory that the log files reside do not have write permissions for at least the group that the ibmproxy daemon runs under. In other words, the log file locations for the logging directives in the ibmproxy.conf file must have write permissions for at least the group defined by the GroupId directive in the ibmproxy.conf file. This is only a problem when the default location of the log files has been changed or when the default UserId or GroupId directive has been changed in the ibmproxy.conf file.

The recommended value for setting the MaxLogFileSize directive is at least 10 M, but less than 200 M. The actual log file size is slightly larger than the size that you set. Setting the value too low affects the proxy performance because the proxy server closes and opens the log file more frequently. On some platforms, setting the value too high causes the proxy to use more memory for I/O buffering. When the log file size becomes larger, it can cause the proxy to run out of memory or look like a memory leak, even though the I/O buffers are controlled by the operating system.

The maximum size can be specified in one of the following units: bytes (B), kilobytes (K), megabytes (M), and gigabytes (G).

Format

MaxLogFileSize maximum {B | K | M | G}

Default

MaxLogfileSize 128 M

If the directive is commented out, however, there is not a limitation on the size of the log file.

MaxPersistRequest -- Specify the maximum number of requests to receive on a persistent connection

Use this directive to specify the maximum number of requests the server receives on a persistent connection. When determining this number, consider the number of images used in your pages. Each image requires a separate request.

Format

MaxPersistRequest number

Default

MaxPersistRequest 5

MaxQueueDepth -- Specify the maximum number of URLs to queue

Use this directive to specify the maximum depth for the cache agent's queue of outstanding page retrieval requests. If you have a large system with a large amount of memory, you can define a larger queue of page retrieval requests without consuming all the available memory.

The queue of URLs to cache is determined at the beginning of each run of the cache agent. If you instruct the cache agent to follow the hypertext links to other URLs, these other URLs are not counted in the cache queue depth. After the value specified in the MaxURLs directive is reached, the cache agent stops, even if there are more URLs in the queue.

Format

MaxQueueDepth maximum_depth

Default

MaxQueueDepth 250

MaxRuntime -- Specify the maximum time for a cache agent run

Use this directive to specify the maximum amount of time for the cache agent to retrieve URLs during a particular run. A value of 0 means the cache agent runs until completion.

Format

MaxRuntime {0 | maximum_time} 

Example

MaxRuntime 2 hours 10 minutes

Default

MaxRuntime 2 hours

MaxSocketPerServer -- Specify the maximum open idle sockets for server

Use this directive to set the maximum number of open idle sockets to maintain for any one origin server. Use this directive only if the ServerConnPool directive is set to on.

Format

MaxSocketPerServer num

Example

MaxSocketPerServer 10

Default

MaxSocketPerServer 5

MaxUrls -- Specify the maximum number of URLs to refresh

Use this directive to specify the maximum number of URLs the cache agent retrieves during a particular run. A value of 0 means there is no limit. When the automatic mode of the cache agent is used, the LoadURL and LoadTopCached directives take precedence over MaxURLs.

Format

MaxURLs maximum_number

Default

MaxURLs 2000

Member -- Specify a member of an array

Use this directive to specify members of the arrays that are shared by the servers using remote cache access.

Note:
When setting up an array, configure the Hostname directive identically on all members of that array.

Format

Member name {
subdirective
subdirective
.
.
}

The following subdirectives are included:

RCAAddr
This required subdirective identifies the IP address or host name for RCA communication.
RCAPort
This required subdirective identifies the port for RCA communication. The port number must be greater than 1024 and less than 65535.
CacheSize {n bytes | n Kbytes | n Mbytes | n Gbytes}
This required subdirective identifies the size of this member's cache, which must be a positive value.
[Timeout n milliseconds | n seconds | n hours | n days | n months | n years | forever]
Identifies how long to wait for this member. n must be a positive integer. Timeout is optional; the default is 1000 milliseconds. Timeout values typically are set in seconds or milliseconds.
[BindSpecific {on | off}]
Allows communications to occur on a private subnet, providing a measure of security. BindSpecific is optional; the default is On.
[ReuseAddr {on | off}]
Allows faster rejoining of the array; Setting this to On allows other processes to steal the port, which can cause undefined behavior. ReuseAddr is optional; the default is Off.

Example

Member bittersweet.chocolate.ibm.com {
  RCAAddr      127.0.0.1
  RCAPort      6294
  CacheSize    25G
  Timeout      500 milliseconds
  BindSpecific On
  ReuseAddr    Off 
  } 

Default

None

Midnight -- Specify the API plugin used to archive logs

Use this directive to specify the application plugin that runs at midnight to archive the logs. This directive is initialized during installation. If you do not include this directive in the configuration file, archiving is not performed.

Format

Midnight /path/file:function_name
/path/file
Specifies the fully qualified file name of the compiled program, including the extension.
function_name
Specifies the name of the application function within your program.

Defaults

NameTrans -- Customize the Name Translation step

Use this directive to specify a customized application function the server calls during the Name Translation step. This code supplies the mechanism for translating the virtual path in the request to the physical path on the server, mapping URLs to specific objects.

Note:
This is not a terminal-mapping rule. The transformed URL still must match one of the terminal-mapping rule directives, such as Exec, Fail, Map, Pass, Redirect, and Service.

Format

NameTrans request_template /path/file:function_name 
  [Server_IP_address | host_name]
request_template
Specifies a template for requests that further determine whether the application function is called. The specification can include the protocol, domain and host; it can be preceded by a slash (/) and can use an asterisk (*) as a wildcard. For example, /front_page.html, http://www.ics.raleigh.ibm.com, /pub*, /*, and * are all valid.
/path/file
Specifies the fully qualified file name of the compiled program, including the extension.
function_name
Specifies the name of the application function within your program.
[Server_IP_address | host_name]
If you are using multiple IP addresses or virtual hosts, determines whether your application function is called only for requests coming in on a specific IP address or for a specific host.

A wildcard character cannot be specified for a server's IP address.

Note:
The directive must be typed on one line, even though it is shown here on two lines for readability.

Example

NameTrans /index.html /api/bin/icsextpgm.so:trans_url

Default

None

NoBG -- Run the Caching Proxy process in foreground

On Linux and UNIX platforms, use this directive to prevent the Caching Proxy server process from automatically running in the background. The directive, which is set to off by default, has the format:

NoBG [on | off]
Note:
The -nobg option for the ibmproxy command is not valid for Windows systems.

Example

NoBG on

Default

NoBG off

NoCaching -- Specify that files with URLs that match a template are not cached

Use this directive to specify that the server does not cache files with URLs matching the specified template. You can include multiple occurrences of this directive in the configuration file. Include a separate directive for each template. The URL template must include the protocol.

If neither the CacheOnly or the NoCaching directive is set, any URL is a candidate for caching.

Format

NoCaching URL_pattern

Example

NoCaching http://joke/*

Default

None

NoLog -- Suppress log entries for specific hosts or domains that match a template

Use this directive to specify that access requests made from specific hosts or domains that match a specified template are not logged. For example, you might not want to log access requests from local hosts.

You can include multiple occurrences of this directive in your configuration file. You can also put multiple templates on the same directive if you separate them by one or more spaces. You can use host names or IP number addresses on the templates.

Note:
To use host name templates, you must set the DNS-Lookup directive to On. If the DNS-Lookup directive is set to Off (the default), you can use IP address templates only.

Format

NoLog  {host_name | IP_address}  [...]

Example

NoLog 128.0.*  *.edu  localhost.*

Default

None

no_proxy -- Specify templates for connecting directly to domains

If you are using the directive http_proxy, ftp_proxy, or gopher_proxy for proxy chaining, you can use this directive to specify the domains that the server connects to directly instead of going through a proxy.

Specify the value as a string of domain names or domain name templates. Separate each entry in the string with a comma (,). Do not use any spaces in the string.

Templates on this directive are entered differently than on other directives. Most importantly, you cannot use the wildcard character (*). You can specify a template by including only the last part of a domain name. The server connects directly to any domains that end with a string matching the templates you specify. This directive applies only to proxy chaining and is equivalent to a direct @/= line in the SOCKS configuration file.

Format

no_proxy  domain_name_or_template[,...]

Example

no_proxy   www.someco.com,.raleigh.ibm.com,.some.host.org:8080

In this example, the server does not go through a proxy for the following requests:

Default

None

NoCacheOnRange -- Specify no caching for Range requests

By default, when receiving a Range request from browsers, Caching Proxy requires a full response from the back-end server. Caching Proxy removes the Range header in the request and then forwards the request to the back-end server. Once the response is cached on the proxy server, the subsequent requests for the same resources are served from the proxy server regardless of whether the requests are Range requests or not. Usually, the default action of Caching Proxy will improve performance and give clients shorter response times. However, if the response cannot be cached, or if the response is very large, the default action will decrease performance.

Use the NoCacheOnRange directive, which specifies no caching for Range requests, to solve the problem that is described when using the default configuration.

When you enable the directive globally in the ibmproxy.conf file, or if you enable it as an option for the PROXY mapping rule, Caching Proxy forwards the Range request header to the back-end server. However, Caching Proxy does not cache the 206 (partial content) response from the back-end server.

Enabling the NoCacheOnRange directive can improve the proxy performance for the following cases:

Format

NoCacheOnRange [on | off]

Example

You can also enable NoCacheOnRange in a proxy mapping rule:

Proxy  /not-cachable/*   http://server.com/no-cachable-resources/*   NoCacheOnRange

Default

NoCacheOnRange off

NoProxyHeader -- Specify the client headers to block

Use this directive to specify client URL headers to block. Any HTTP header sent by a client can be blocked, including required headers. Use extreme care when blocking headers. Common headers include:

See the HTTP protocol specification for details of these and other headers. You can specify this directive multiple times.

Format

NoProxyHeader header

Example

NoProxyHeader Referer:

Default

None

NumClients -- Specify the number of cache agent threads to use

Use this directive to specify the number of threads the cache agent uses to retrieve pages in the queue. Base the number of threads on the speed of your internal network and your connection to the Internet. The allowable range is 1 through 100.

Note:
Using more than six threads can possibly lead to excessively rapid requests on content servers.

Format

NumClients number

Default

NumClients 4

ObjectType -- Customize the Object Type step

Use this directive to specify a customized application function that the server calls during the Object Type step. This code locates the requested object in the file system and specifies its MIME type.

Format

ObjectType request_template /path/file:function_name
request_template
Specifies a template for requests that further determine whether your application function is called. The specification can include the protocol, domain, and host; it can be preceded by a slash (/) and can use an asterisk (*) as a wildcard. For example, /front_page.html, http://www.ics.raleigh.ibm.com, /pub*, /*, and * are all valid.
/path/file
Specifies the fully qualified file name of the compiled program, including the extension.
function_name
Specifies the name of the application function within your program.

Example

ObjectType /index.html /api/bin/icsextpgm.so:obj_type

Default

None

OptimizeRuleMapping -- Optimize the rule mapping process for incoming requests when the number of rules increases

This directive speeds up the rule mapping process for incoming requests when the number of rules increases.

When you enable the OptimizeRuleMapping directive, instead of mapping incoming URI requests against each rule one-by-one, the proxy maps the URI against a prefix tree. The prefix tree helps proxy remove the redundant string comparison among the mapping rules. As a result, Caching Proxy achieves better performance when the number of rules in your configuration is greater than 300.

Format

OptimizeRuleMapping  [on | off ]

Default

OptimizeRuleMapping off 

OutputTimeout -- Specify the output timeout

Use this directive to set the maximum time allowed for the server to send output to a client. The time limit applies to requests for local files and requests for which the server is acting as a proxy. The time limit does not apply for requests that start a local CGI program.

If the server does not send the complete response within the time limit specified on this directive, the server drops the connection. Specify the time value in any combination of hours, minutes (or mins), and seconds (or secs).

Format

OutputTimeout time 

Default

OutputTimeout 30 minutes

PacFilePath -- Specify the directory containing the PAC files

Use this directive to specify the directory containing the proxy autoconfiguration files generated by using the remote config PAC file form.

Format

PacFilePath directory_path

Defaults

Pass -- Specify the template for accepting requests

Use this directive to specify a template for requests that you want to accept and respond to with a file from your server. After a request matches a template on a Pass directive, the request is not compared to request templates on any subsequent directives.

Format

Pass  request_template [file_path [server_IP_address | host_name]]
request_template
Specifies a template for requests that you want the server to accept and respond to with a file.

You can use an asterisk (*) as a wildcard in the template. The tilde character (~) just after a slash (/) must be explicitly matched; a wildcard cannot be used to match it.

[file_path]
Specifies the path to the file that the server is to return. The file_path can contain a wildcard if the request_template has one. The part of the request that matches the request_template wildcard is inserted in place of the wildcard in file_path.

This parameter is optional. If you do not specify a path, the request itself is used as the path.

[server_IP_address | host_name]
If you are using multiple IP addresses or virtual hosts, use this parameter to specify an IP address or a host name. The server uses the directive only for requests that come to the server on this IP address or for this host. For an IP address, this is the address of the server’s network connection, not the address of the requesting client.

You can specify an IP address (for example, 240.146.167.72) or you can specify a host name (for example, hostA.raleigh.ibm.com).

This parameter is optional. Without this parameter, the server uses the directive for all requests regardless of the IP address the requests come in on or the host name in the URL.

A wildcard character cannot be specified for a server's IP address.

Examples

Defaults

PersistTimeout -- Specify the time to wait for the client to send another request

Use this directive to specify the length of time that the server waits between client requests before canceling a persistent connection. The time can be specified in any valid time increment, but it is usually specified in seconds or minutes.

The server uses a different timeout directive, the InputTimeout, to determine how long to wait for the client to send the first request after the connection is established. For more information about the input timeout, see InputTimeout -- Specify the input timeout.

After the server sends its first response, it uses the value set for the PersistTimeout directive to determine how long to wait for each subsequent request before canceling the persistent connection.

Format

PersistTimeout  time

Default

PersistTimeout 4 seconds

PICSDBLookup -- Customize the PICS label retrieval step

Use this directive to specify a customized application function that the server calls to retrieve PICS labels for a specified URL. The function can either dynamically create a PICS label for the requested file or search for a PICS label in an alternative file or database.

Format

PICSDBLookup  /path/file:function_name
/path/file
Specifies the fully qualified file name of the compiled program, including the extension.
function_name
Specifies the name of application function within your program.

Example

PICSDBLookup  /api/bin/icsext05.so:get_pics

Default

None

PidFile (Linux and UNIX only) -- Specify the file in which to store the process ID of Caching Proxy

Linux and UNIX only. Use this directive to specify the location of the file that contains the process ID of Caching Proxy. When the server process starts, it records its process ID (PID) in a file. If multiple instances of the server are running on a single system, each instance must have its own PidFile directive.

Format

PidFile path_to_pid_file_info

Example

PidFile /usr/pidinfo

Defaults

PKCS11DefaultCert, PKCS11DriverPath, PKCS11TokenPassword -- Supports IBM 4960 PCI Cryptographic Accelerator Card (AIX only)

On AIX systems, to support the IBM 4960 PCI Cryptographic Accelerator Card, additional directives are provided.

Use these directives to allow the proxy to load the device driver and open the token device. When the device driver is loaded, the proxy server will automatically use the device to increase SSL communication speed.

See also, SSLCryptoCard -- Specify the installed cryptographic card.

Format

PKCS11DefaultCert default_cert_label 

Specify the default SSL certificate label stored on the token device.

PKCS11DriverPath absolute_path_to_the_card_driver 

Specify the absolute path to the device driver for the Cryptographic Accelerator Card.

PKCS11TokenPassword password 

Specify the password to open the token device.

Example

PKCS11DefaultCert  MyDefaultCertInTheToken
PKCS11DriverPath /usr/lib/pkcs11/PKCS11_API.so
PKCS11TokenPassword MyPasswordToOpenTheToken

Default

None

Plugin module directives

The directives listed below have been added to the Caching Proxy ibmproxy.conf file to enable new features and plugins. Configuration and Administration forms are not available for editing most of these directives. A standard text editor, such as vi or emacs, must be used to manually edit them. Further information on each of these new directives appears in this chapter, in alphabetical order.

In the ibmproxy.conf file, directives used to configure Caching Proxy plugin modules must be entered in the following format:

<MODULEBEGIN> plugin name
subdirective1
subdirective2
<MODULEEND>

Each plugin program parses the ibmproxy.conf file and reads only its own block of subdirectives. The Caching Proxy parser disregards everything between <MODULEBEGIN> and <MODULEEND>.

Caching Proxy plugin modules and some new features require that API directives be added to the ibmproxy.conf file. Because the proxy server interacts with the plugin modules in the order in which they are listed, take care when ordering the directives within the proxy configuration file. Prototype directives (in the form of comments) have been added to the API section of the ibmproxy.conf file. These API directives are in a purposeful order. When adding API directives to enable new features and plugin modules, order the directives as shown in the prototype section of the configuration file. Alternatively, uncomment and edit, if necessary, API directives to include support for each desired function or plugin. Add user-generated plugin modules after those supplied with the product.

Port -- Specify the port on which the server listens for requests

Use this directive to specify the number of the port on which the server listens for requests. The standard port number for HTTP is 80. Other port numbers lower than 1024 are reserved for other TCP/IP applications and must not be used. Common ports used for proxy Web servers are 8080 and 8008.

When a port other than 80 is used, clients are required to include a specific port number on requests to the server. The port number is preceded by a colon (:) and placed after the host name on the URL. For example, from the browser, the URL http://www.turfco.com:8008/ requests the default welcome page from a host named www.turfco.com that is listening on port 8008.

You can use the -p option on the ibmproxy command to override this setting when starting the server.

Format

Port number

If you change this directive, you must manually stop and then start your server again for the change to take effect. The server does not recognize the change if you only restart it. (See Starting and stopping Caching Proxy.)

Default

Port 80

PostAuth -- Customize the PostAuth step

Use this directive to specify a customized application function that the server calls during the PostAuth step. This code is executed regardless of the return codes from previous steps or other PostAuth handlers. It allows you to clean up any resources allocated to process the request.

Format

PostAuth  /path/file:function_name
/path/file
Specifies the fully qualified file name of the compiled program, including the extension.
function_name
Specifies the name of the application function within the program.

Example

AuthExit  /ics/api/bin/icsext05.so:post_exit

Default

None

PostExit -- Customize the PostExit step

Use this directive to specify a customized application function that the server calls during the PostExit step. This code is executed regardless of the return codes from previous steps or other PostExit handlers. It allows you to clean up any resources allocated to process the request.

Format

PostExit  /path/file:function_name
/path/file
Specifies the fully qualified file name of the compiled program, including the extension.
function_name
Specifies the name of the application function within the program.

Example

PostExit  /ics/api/bin/icsext05.so:post_exit

Default

None

PreExit -- Customize the PreExit step

Use this directive to specify a customized application function that the server calls during the PreExit step. This code is executed after a client request is read but before any other processing occurs. You can call the GoServe module during this step.

Format

PreExit /path/file:function_name
/path/file
Specifies the fully qualified file name of the compiled DLL, including the extension.
function_name
Specifies the name of the application function within the program.

Example

PreExit  /ics/api/bin/icsext05.so:pre_exit

Default

None

Protect -- Activate a protection setup for requests that match a template

Use this directive to activate protection setup rules for requests that match a template.

Note:
For protection to work properly, the DefProt and Protect directives must be placed before any Pass, Exec, or Proxy directives in the configuration file.

A protection setup is defined with protection subdirectives. The format of the Protect directive depends on whether you want to point to a label or file containing the protection subdirectives or to include the protection subdirectives inline as part of the Protect directive.

Format

This parameter can take the following forms:

The following parameters are used:

request_template
Specifies a template for requests for which to activate protection. The server compares incoming client requests to the template and activates protection if there is a match.
[setup_file | label]
If you are pointing to a label or file containing the protection subdirectives, this parameter specifies the protection setup to activate for requests that match request_template.

This parameter is optional. If it is omitted, the protection setup is defined by the most recent DefProt directive that contains a matching template.

[FOR server_IP_address | host_name]
If you are using multiple IP addresses or virtual hosts, use this parameter to specify an IP address or a host name. The server uses the directive only for requests that come to the server on this IP address or for this host. For an IP address, this is the address of the server’s network connection, not the address of the requesting client. If you protect an IP address, both the IP address and the fully qualified hostname are protected. However, if the server is called from within its network using a name other than the fully qualified hostname, such as by using an entry in a hostname file, it is not protected.

Example:

Protect http://x.x.x.x  PROT-ADMIN

Within a Web browser:

Example:

Protect http://hostname.example.com  PROT-ADMIN

Within a Web browser:

You can specify an IP address (for example, FOR 240.146.167.72), or you can specify a host name (for example, FOR hostA.bcd.com ).

Wildcard characters cannot be used to specify server IP addresses.

This parameter is optional. Without this parameter, the server uses the directive for all requests regardless of the IP address the requests come in on or the host name in the URL.

Note:
The [server_IP_address | host_name] parameter is used with either the [setup_file | label] parameter or the subdirective value parameter.
  • To use [server_IP_address | host_name] with [setup_file | label], you must put FOR, or some other character string (without blanks), between the [setup_file | label] parameter and the [server_IP_address | host_name] parameters.
  • To use [server_IP_address | host_name] with subdirective value parameters, do not include FOR before the IP_address or host_name.
subdirective value
To include the protection subdirectives as part of the Protect directive, use this parameter. For descriptions of the protection subdirectives, see the following:

Examples

Default

By default, protection is provided for the Configuration and Administration forms by a Protect directive with a request template of /admin-bin/*.

Protection -- Define a named protection setup within the configuration file

Use this directive to define a protection setup within the configuration file. You give the protection setup a name and define the type of protection by using protection subdirectives.

Notes:
  1. In the configuration file, place Protection directives before any DefProt or Protect directives that point to them.
  2. To use domain names in your protection rules, set the DNS-Lookup directive to on.

Format

Protection label_name  {
    subdirective  value
    subdirective  value
    .
    .
    .
  }
label_name
Specifies the name to associate with this protection setup. The name can then be used by subsequent DefProt and Protect directives to point to this protection setup.
subdirective value
The subdirectives are enclosed in braces ({ }). The left brace character must be the last character on the same line as the label_name. Each subdirective follows on its own line. The right brace character must be on its own line following the last subdirective line.. No comment lines can appear between the braces.

See Protection subdirectives -- Specify how a set of resources is protected for descriptions of the protection subdirectives.

Example

Protection NAME-ME   {
   AuthType Basic
   ServerID restricted
   PasswdFile  /WWW/password.pwd
   GroupFile   /WWW/group.grp
   GetMask groupname
   PutMask groupname
}

Default

Protect /admin-bin/* {
  ServerId     Private_Authorization
  AuthType     Basic
  GetMask      All@(*)
  PutMask      All@(*)
  PostMask     All@(*)
  Mask         All@(*)
  PasswdFile   /opt/ibm/edge/cp/server_root/protect/webadmin.passwd
}

Protection subdirectives -- Specify how a set of resources is protected

The following are descriptions of the protection subdirectives that can be used in a protection setup. The subdirectives are in alphabetical order.

The protection setups can be either in separate files or included in the configuration file as part of DefProt, Protect, or Protection directives.

AuthType -- Specify the authentication type

Use this Protection subdirective when limiting access based on user names and passwords. Specify the type of authentication to use when the client sends a password to the server. With basic authentication (AuthType Basic), passwords are sent to the server as plain text. They are encoded, but not encrypted.

Default
AuthType Basic

DeleteMask -- Specify the user names, groups, and addresses that are allowed to delete files

Use this Protection subdirective to specify user names, groups, and address templates authorized to make DELETE requests to a protected directory.

Example
DeleteMask authors,(niceguy,goodie)@45.96.3.1,128.0.*.*

GetMask -- Specify the user names, groups, and addresses allowed to get files

Use this Protection subdirective to specify user names, groups, and address templates authorized to make GET requests to a protected directory.

Example
GetMask authors,(niceguy,goodie)@45.96.3.1,128.0.*.*
Default
GetMask  All@(*)

GroupFile -- Specify the location of the associated group file

Use this Protection subdirective to specify the path and file name of the server group file that the protection setup uses. The groups defined within the server group file can then be used by the following:

Example
GroupFile /docs/etc/WWW/restrict.group

Mask -- Specify the user names, groups, and addresses allowed to make HTTP requests

Use this subdirective to specify user names, groups, and address templates authorized to make HTTP requests that are not covered by other mask subdirectives.

Examples
Mask authors,(niceguy,goodie)@45.96.3.1,128.0.*.*
Note:
When you use the Mask directive, it is important to note that Masks are case sensitive. The following is an example of a Mask protection specified on a user ID:
MASK WEBADM,webadm

PasswdFile -- Specify the location of the associated password file

Use this Protection subdirective when limiting access based on user names and passwords. Specify the path and name of the password file that this protection setup is to use.

Because some browsers cache User IDs and passwords by security realm (ServerID) within a host, follow these guidelines when specifying ServerID and password files:

Example
PasswdFile /docs/etc/WWW/restrict.password
Note:
If the path or file name of the password file contains embedded blanks, then the entire path and file name must be enclosed in quotation marks ("".)
PasswdFile "c:\test this\admin.pwd"   

PostMask -- Specify the user names, groups, and addresses allowed to post files

For a secure server, use this Protection subdirective to specify users, groups, and address templates authorized to make POST requests to a protected directory.

Example
PostMask authors,(niceguy,goodie)@45.96.3.1,128.0.*.*

PutMask -- Specify the users names, groups, and addresses allowed to put files

Use this Protection subdirective to specify users, groups, and address templates authorized to make PUT requests to a protected directory.

Example
PutMask authors,(niceguy,goodie)@45.96.3.1,128.0.*.*

ServerID -- Specify a name to associate with the password file

Use this Protection subdirective when limiting access based on user names and passwords. Specify a name that you want to associate with the password file being used. The name does not need to be a real machine name.

The name is used as an identifier to the requester. Because different protection setups can use different password files, associating a name with the protection setup can help the client decide which password to send. Most clients display this name when prompting for a user name and password.

Because some browsers cache user IDs and passwords by security realm (ServerID) within a host, follow these guidelines when specifying ServerID and password files:

Example
ServerID restricted

Proxy -- Specify proxy protocols or reverse proxy

Use this directive to indicate which protocols the Caching Proxy is to process and map a request to a server. Valid protocols are http, ftp, and gopher.

The proxy directive passes the request to a remote server. For example, the following directive causes all requests to be forwarded to the designated URL:

Proxy /*   http://proxy.server.name/* 

For a secure reverse proxy server, use the following directive:

Proxy /*  https://proxy.server.name/*

If you want your proxy server to be less restrictive, uncomment the following directives from your configuration file. However, these directives may introduce a security problem when proxy is configured as a reverse proxy.

Proxy http:*
Proxy ftp:*
Proxy gopher:*

Optional parameters:

Format

Proxy request_template target_server_path [[ip]:port]
[UseSession | NoCaching | NoCacheOnRange | NoJunction | JunctionPrefix:/url_prefix]

Example

The following is an example of the UseSession option for the Proxy directive:

Proxy  /abc/*   http://server1/default/abc/*  :80  UseSession

When the incoming client request comes from port 80, and if the URL on the client request matches the pattern /abc/*, then the URL is mapped to http://server1/default/abc/* .

Defaults

None.

ProxyAccessLog -- Name the path for the proxy access log file

Use this directive to specify the path and name for the file where you want the server to log access statistics for proxy requests. By default, the server writes an entry to this log each time it acts as a proxy for a client request. You can use the NoLog directive if you do not want to log requests from certain clients.

The server starts a new log file each day at midnight if it is running. Otherwise, the server starts a new log file the first time you start it on any day. When creating the file, the server uses the file name you specify and appends a date suffix or extension. The date suffix or extension is in the format Mmmddyyyy, where Mmm is the first three letters of the month; dd is the day of the month; and yyyy is the year.

It is a good idea to remove old log files, because they can consume a significant amount of space on your hard drive.

Format

ProxyAccessLog path/file

Defaults

ProxyAdvisor -- Customize the servicing of proxy requests

Use this directive to specify a customized application you want the server to call during the Proxy Advisor step. This code will service the request.

Format

ProxyAdvisor /path/file:function_name					
/path/file
Specifies the fully qualified file name of the compiled program.
function_name
Specifies the name of the application function within the program.
Example
ProxyAdvisor /api/bin/customadvise.so:proxyadv

Default

None

ProxyForwardLabels -- Specify PICS filtering

Use the ProxyForwardLabels directive to specify PICS filtering at the proxy server and at the client, or at two proxies in a proxy hierarchy.

If ProxyForwardLabels is set to on, the proxy server generates PICS-Label: HTTP headers for all PICS labels found, including labels from the origin server, label bureaus, the Caching Proxy's label cache, and label-supplier plugins.

If ProxyForwardLabels is set to Off, PICS-Label: HTTP headers are not generated.

Format

ProxyForwardLabels {on | off}

Default

ProxyForwardLabels Off

ProxyFrom -- Specify a client with a From: header

Use this directive to generate a From: header. This is typically used to give an e-mail address of the proxy administrator.

Format

ProxyFrom e-mail_address

Example

The setting ProxyFrom webmaster@proxy.ibm.com results in the following header change:

Original header Modified Header
Location: http://www.ibm.com/ Location: http://www.ibm.com/
Last Modified: Tue 5 Nov 1997 10:05:39 GMT Last Modified: Tue 5 Nov 1997 10:05:39 GMT
Pragma: no-cache From: webmaster@proxy.ibm.com
Pragma: no-cache

Default

None

ProxyIgnoreNoCache -- Ignore a reload request

Use this directive to specify how the server reacts when users click Reload on the browser. If the ProxyIgnoreNoCache directive is set to on, during periods of high load, the server does not request the page from the destination server and supplies the cached copy of the file if it is available. The server essentially disregards the Pragma: no-cache header sent from the browser.

Format

ProxyIgnoreNoCache  {on | off}

Default

ProxyIgnoreNoCache off

ProxyPersistence -- Allow persistent connections

Use this directive to specify whether a persistent connection is maintained with the client. A persistent connection reduces waiting time for users and reduces the CPU load on the proxy server, but it requires more resources. More threads, and therefore more memory on the proxy server, are required for a persistent connection.

Persistent connections must not be used on a multilevel proxy server setup if any of the proxies is not HTTP 1.1 compliant.

Format

ProxyPersistence {on | off}

Default

ProxyPersistence on

ProxySendClientAddress -- Generate the Client IP Address: header

Use this directive to specify whether the proxy forwards the IP address of the client to the destination server.

Format

ProxySendClientAddress  {Client_IP: | OFF} 

Example

The directive ProxySendClientAddress Client-IP: results in the following header change:

Original header Modified Header
Location: http://www.ibm.com/ Location: http://www.ibm.com
Last Modified: Tue 5 Nov 1997 10:05:39 GMT Last Modified: Tue 5 Nov 1997 10:05:39 GMT
Pragma: no-cache Client-IP: 0.67.199.5
Pragma: no-cache

Default

None

ProxyUserAgent -- Modify User Agent string

Use this directive to specify a User Agent string that replaces the string that the client sends. This allows greater anonymity while visiting Web sites. However, some sites have customized pages based on the User Agent string. Using the ProxyUserAgent directive prevents these custom pages from being displayed.

Format

ProxyUserAgent product_name/version

Example

The directive ProxyUserAgent Caching Proxy/7.0 results in the following header change:

Original header Modified header
Location: http://www.ibm.com/ Location: http://www.ibm.com
Last Modified: Tue 5 Nov 1997 10:05:39 GMT Last Modified: Tue 5 Nov 1997 10:05:39 GMT
User Agent: Mozilla/ 2.02 OS2 User Agent: Caching Proxy/7.0
Pragma: no-cache Pragma: no-cache

Default

None

ProxyVia -- Specify format of HTTP header

Use this directive to control the format of the HTTP header. There are four possible values for this directive. If ProxyVia is set to Full, the Caching Proxy adds a Via header into the request or reply; if a Via header is already in the stream, the Caching Proxy adds host information at the end. If set to Set, the Caching Proxy sets the Via header to host information; if a Via header is already in the stream, the Caching Proxy removes it. If set to Pass, the Caching Proxy forwards any header information as is. If set to Block, the Caching Proxy does not forward any Via header.

Format

ProxyVia {Full | Set | Pass | Block}

Example

ProxyVia Pass

Default

ProxyVia Full

ProxyWAS -- Specify that requests are sent to WebSphere Application Server

This applies to reverse proxy configurations only.

The ProxyWAS mapping directive works identically to the Proxy directive, but also indicates to Caching Proxy that matching requests are directed to a WebSphere Application Server. For examples on using this directive, see Proxy -- Specify proxy protocols or reverse proxy.

Format

ProxyWAS request_template target_server_path [[ip]:port] 
[UseSession | NoCaching | NoCacheOnRange | NoJunction | JunctionPrefix:/url_prefix]

Default

None

PureProxy -- Disable a dedicated proxy

Use this directive to specify whether the server is acting as a proxy server or as a proxy and content server. It is recommended that you use the Caching Proxy as a proxy only.

Format

PureProxy {on | off}

Default

PureProxy on

PurgeAge -- Specify the age limit for a log

Use this directive to specify the age of a log, in days, before it is purged. If PurgeAge is set to 0, the log is never deleted.

Note:
The plugin never deletes the log for the current day or the preceding day.

Format

PurgeAge number

Default

PurgeAge 7

Related directives

PurgeSize -- Specify the limit for the size of the log archive

Use this directive to specify how large, in megabytes, the log files can grow before the log archive is purged. If the PurgeSize directive is set to 0, there is no size limit and no files are deleted.

The setting for PurgeSize refers to all the logs of a log type. For instance, if you are logging errors (that is, if an ErrorLog entry has been made in the configuration file) and PurgeSize is defined as 10 MB, the Caching Proxy calculates the sizes of all the error logs, adds them together, then deletes logs until the total size is less than 10 MB.

Note:
The plugin never deletes the log for the current day or the preceding day. When log files are deleted, the oldest logs are deleted first, until the size of each log type's log files is less than or equal to the value defined by PurgeSize (in megabytes).

Format

PurgeSize number_of_MB

Default

PurgeSize 0

Related directives

RCAConfigFile -- Specify an alias for ConfigFile

Use this directive to specify the name and location of the Remote Cache Access configuration file.

Note:
The RCA configuration file has been merged into the file ibmproxy.conf. For backward compatibility, RCAConfigFile is supported as an alias for ConfigFile.

Format

RCAConfigFile /etc/file_name

Example

RCAConfigFile /etc/user2rca.conf

Default

RCAConfigFile /etc/rca.conf

RCAThreads -- Specify the number of threads per port

Use this directive to specify the number of threads working on an RCA port.

Format

RCAThreads number_of_threads

Example

RCAThreads 50

Default

MaxActiveThreads x [(ArraySize -1) / (2 x ArraySize -1)]

ReadTimeout -- Specify the time limit for a connection

Use this directive to specify the time limit allowed without network activity before a connection is canceled.

Format

ReadTimeout time

Default

ReadTimeout 5 minutes

Redirect -- Specify a template for requests sent to another server

Use this directive to specify a template for requests that you want to accept and send to another server. After a request matches a template on a Redirect directive, the request is not compared to templates on any other directives in the configuration file.

Format

Redirect request_template URL  [server_IP_address | host_name]
request_template
Specifies a template for requests that you want your server to send to another server.

You can use an asterisk (*) as a wildcard in the template. The tilde character (~) just after a slash (/) must be explicitly matched; a wildcard cannot be used to match it.

URL
Specifies the URL request that the server sends to another server. The response to this request goes to the original requester without any indication that it did not come from your server.

URL must contain a protocol specification and the name of the server to which the request is sent. It can also contain a path or file name. If request_template uses a wildcard, the path or file name on URL can also use a wildcard. The part of the original request that matches the wildcard on request_template is inserted in place of the wildcard on URL.

[server_IP_address | host_name]
If you are using multiple IP addresses or virtual hosts, use this parameter to specify an IP address or a host name. The server uses the directive only for requests that come to the server on this IP address or for this host. For an IP address, this is the address of the server’s network connection, not the address of the requesting client.

You can specify an IP address (for example, 240.146.167.72) or you can specify a host name (for example, hostA.bcd.com).

This parameter is optional. Without this parameter, the server uses the directive for all requests regardless of the IP address the requests come in on or the host name in the URL.

A wildcard character cannot be specified for a server's IP address.

[redirectcode: redirection_code]
This is an optional tag used to specify the return code during redirection. redirection_code is the HTTP return code that the proxy server sends to the client. By default, the return code is 302, but 301 and similar codes are valid.

Examples

Default

None

RegisterCacheIdTransformer -- Cache more than one variant of a resource based on the Cookie header

Use this directive to allow Caching Proxy to cache more than one variant of a resource (URI) based on the Cookie header.

Note:
If cookies are disabled on the client browsers, clients can access the same cached object.

For more information, see SupportVaryHeader -- Cache more than one variant of a resource based on the HTTP Vary header.

Format

RegisterCacheIdTransformer Cookie cookie-name

The cookie-name is the name in the Cookie header in the client's request.

Example

RegisterCacheIdTransformer Cookie Usergroup

For an example of using this directive in conjunction with SupportVaryHeader, seeSupportVaryHeader -- Cache more than one variant of a resource based on the HTTP Vary header.

Default

None

ReversePass -- Intercept automatically redirected requests

This applies to reverse proxy configurations only.

The ReversePass mapping directive examines the server response stream to detect requests that are rewritten as a result of automatic redirection. Typically, when a server returns an HTTP code in the 3xx class (for example, 301, moved permanently, or 303, see other), the server sends a message with the reply that instructs the requesting client to direct future requests to the correct URL and IP address. In the case of a reverse proxy setup, a redirection message from the origin server can cause client browsers to bypass the proxy server for subsequent requests. To avoid having clients directly contact the origin server, use the ReversePass directive to intercept requests that are made specifically to the origin server.

Unlike other mapping directives, which process the request stream, ReversePass matches its template to the response stream. The response stream is the reply that the proxy server obtains from the origin server and sends to the client.

Format

ReversePass rewritten_URL proxy_URL [host:port]

The host:port option allows the proxy to apply a different ReversePass rule based on the backend server hostname and port.

Examples

Note:
The contents of the proxy_URL pattern, up to the wild card (*), must match exactly what the back-end server sends in the location header or the directive fails.

Default

None

RewriteSetCookieDomain -- Specify the domain pattern that needs to be rewritten

This applies to reverse proxy configurations only.

Use this directive to specify the domain pattern that needs to be rewritten. The directive will transform the domain from domain_pattern1 to domain_pattern2.

Format

RewriteSetCookieDomain domain_pattern1 domain_pattern2

Example

RewriteSetCookieDomain .internal.com .external.com

Default

None

Related directives

RTSPEnable -- Enable RTSP redirection

This applies to reverse proxy configurations only.

This directive enables or disables RTSP redirection. Options are on or off.

Format

RTSPEnable {on | off}

Example

RTSPEnable  on

Default

None

rtsp_proxy_server - Specify servers for redirection

This applies to reverse proxy configurations only.

This directive is used to specify RTSP proxy servers to receive redirected requests. Different servers can be specified for different types of streams. The format of this directive is:

rtsp_proxy_server server dns address[:port] default rank [list of mime types] 

Example

rtsp_proxy_server    rproxy.mycompany.com:554     1
rtsp_proxy_server    fw1.mycompany.com:554        2
rtsp_proxy_server    fw1.mycompany.com:555        3
rtsp_proxy_server    fw2.mycompany.com:557        4

Default

None

rtsp_proxy_threshold -- Specify number of requests before redirection to a cache

This applies to reverse proxy configurations only.

This directive specifies how many requests are received before an RTSP request is redirected to a proxy server rather than to the origin server. RealNetworks proxies cache streams on the first request, and caching initially incurs at double the bandwidth of receiving a stream. Specifying a threshold greater than one prevents requests made only once from being cached. The format of this directive is:

rtsp_proxy_threshold number_of_hits

Example

rtsp_proxy_threshold 5

Default

None

rtsp_url_list_size -- Specify number of URLs in proxy memory

This applies to reverse proxy configurations only.

This directive specifies the number of unique URLs that are kept in memory for redirection. The proxy refers to this list to determine whether a given URL has been encountered before. Larger list sizes improve the proxy server's ability to send a subsequent request to the same proxy server that received the previous request, but each list entry consumes approximately 16 bytes of memory.

Format

rtsp_url_list_size size_of_list

Example

rtsp_url_list_size 8192

Default

None

RuleCaseSense -- Maps requests from application URLs that are not case sensitive

By Default, when Caching Proxy maps requests against rules defined in the ibmproxy.conf file, the matching process is case sensitive. However, some application URLs are not case sensitive. In order to handle these requests correctly, RuleCaseSense directive is provided. When the directive is set to off, proxy will match requests without case sensitivity.

Note:
The directive is a global directive, and it applies to all mapping rules defined.

Format

RuleCaseSense {on | off}

Default

RuleCaseSense  on

ScriptTimeout - Specify the timeout setting for scripts

Use this directive to set the time allowed for a CGI program started by the server to finish. When the time expires, the server ends the program. On Linux and UNIX platforms, this is done with the KILL signal.

Enter the time value using any combination of hours, minutes (or mins), and seconds (or secs).

Format

ScriptTimeout timeout

Default

ScriptTimeout 5 minutes

SendHTTP10Outbound -- Specify the protocol version for proxied requests

Use this directive to specify that requests sent from the Caching Proxy to a downstream server are to use the HTTP Version 1.0 protocol. (A downstream server is another proxy server in a chain of proxies or an origin server that processes the request.)

If this directive is used, the Caching Proxy identifies HTTP 1.0 as the protocol in the request line. Only HTTP 1.0-specific functionality and certain HTTP 1.1 functions, such as cache-control headers, which are supported by most HTTP 1.0 servers, are sent to the downstream server. Use this directive if you have a downstream server that does not handle HTTP 1.1 requests correctly.

If the SendHTTP10Outbound directive is not specified, the Caching Proxy identifies HTTP 1.1 as the protocol in the request line. HTTP 1.1 functionality, such as persistent connections, can also be used in the request.

Format

SendHTTP10Outbound url_pattern

Examples

This directive can be specified multiple times, for example:

SendHTTP10Outbound http://www.hosta.com/*
SendHTTP10Outbound http://www.hostb.com/* 

For backward compatibility, the previous syntax of SendHTTP10Outbound is handled as follows:

Note:
If both SendHTTP10Outbound off and SendHTTP10Outbound url_pattern are specified, then SendHTTP10Outbound off is ignored, but a warning message is issued.

Default

None

SendRevProxyName -- Specify the Caching Proxy host name in the HOST header

This applies to reverse proxy configurations only.

When functioning as a reverse proxy, the Caching Proxy receives HTTP requests from a client and sends the requests to the origin server. By default, the Caching Proxy writes the origin server's host name in the HOST header of the request that it sends to the origin server. If the SendRevProxyName directive is set to yes, the Caching Proxy writes its own host name in the HOST header instead. This directive can be used to enable special configuration for back-end servers because it allows the request to the origin server to always appear to come from the proxy server, even in the case where the request is redirected from one back-end server to another.

This directive differs from the ReversePass mapping directive as follows: the ReversePass directive intercepts requests with a specified syntax and substitutes different request content that you specify. The SendRevProxyName directive can be set only to substitute the Caching Proxy host name for the origin server host name. This directive is not useful in configuring Application Service at the Edge.

Format

SendRevProxyName  {yes | no}

ServerConnGCRun -- Specify the interval at which to run garbage collection thread

This directive sets the interval at which the garbage collection thread check for server connections that have timed out (set with the ServerConnTimeout directive). Use this directive only if the ServerConnPool directive is set to on.

Format

ServerConnGCRun time_interval

Example

ServerConnGCRun 2 minutes

Default

ServerConnGCRun 2 minutes

ServerConnPool -- Specify the pooling of connections to origin servers

This directive allows the proxy to pool together its outgoing connections to origin servers. Setting this directive to on enhances performance and takes better advantage of origin servers that allow persistent connections. You can also specify how long to maintain an unused connection via the ServerConnTimeout directive.

Note:
This directive is best enabled in a controlled environment; it can degrade performance in a forward proxy situation or one where the origin servers are not HTTP 1.1 compliant.

Format

ServerConnPool {on | off}

Default

ServerConnPool off

ServerConnTimeout -- Specify maximum inactive period

Use this directive to limit the time allowed without network activity before cancelling the connection. Use this directive only if the ServerConnPool directive is set to on.

Format

ServerConnTimeout time-spec

Example

ServerConnTimeout 30 seconds

Default

ServerConnTimeout 10 seconds

ServerInit -- Customize the Server Initialization step

Use this directive to specify a customized application function that the server calls during its initialization routines. This code is executed before any client requests are read and whenever the server is restarted.

If you are using the GoServe modules in the PreExit or Service steps, you need to call the gosclone module here.

Format

ServerInit /path/file:function_name [initialization_string]
/path/file
Specifies the fully qualified file name of the compiled program, including the extension.
function_name
Specifies the name of the application function within your program.
initialization_string
Optional; specifies a text string that is passed to the application function.

Example

ServerInit   /ics/api/bin/icsext05.so:svr_init

Default

None

ServerRoot -- Specify the directory where the server program is installed

Use this directive to specify the directory where the server program is installed (the current working directory of the server). Logging directives use this current working directory as the default root when relative path names are used.

On Windows systems, the directory is identified during installation.

Format

ServerRoot  directory_path

Defaults

Note:
You can change the default, but it has no effect on how the server processes requests.
Note:
PASS and EXEC rules can be independent of this directory.

ServerTerm -- Customize the Server Termination step

Use this directive to specify a customized application function that the server calls during the Server Termination step. This code is executed when an orderly shutdown occurs and whenever the server is restarted. It allows you to release resources allocated by a PreExit application function.

Format

ServerTerm  /path/file:function_name
/path/file
Specifies the fully qualified file name of the compiled program, including the extension.
function_name
Specifies the name of the application function within your program.

Example

ServerTerm  /ics/api/bin/icsext05.so:shut_down

Default

None

Service -- Customize the Service step

Use this directive to specify a customized application function that the server calls during the Service step. This code services the client request. For example, it sends the file or runs the CGI program.

There is no default for this directive. If the request matches a Service rule (that is, if an application function specified on a Service directive is executed), but the function returns HTTP_NOACTION, the server generates an error and the request fails.

Format

Service request_template/path/file:function_name 
[server_IP_address | host_name]
request_template
Specifies a template for requests that further determine whether the application function is called. The specification can include the protocol, domain, and host; it can be preceded by a slash (/) and can use an asterisk (*) as a wildcard. For example, /front_page.html, http://www.ics.raleigh.ibm.com, /pub*, /*, and * are all valid.
/path/file
Specifies the fully qualified file name of the compiled program, including the extension.
function_name
Specifies the name of the application function within your program.
[Server_IP_address | host_name]
If you use multiple IP addresses or virtual hosts, this parameter determines whether your application function is called only for requests coming in on a specific IP address or for a specific host.

A wildcard character cannot be specified for a server's IP address.

Examples

Service  /index.html /ics/api/bin/icsext05.so:serve_req
Service  /cgi-bin/hexcalc* /ics/api/calculator:HEXcalc*
Note:
If you want full path translation, including query_string, you must have an asterisk (*) in both the request_template and in the path/file:function_name, as shown in the second example.

Default

None

SignificantURLTerminator -- Specify a terminating code for URL requests

Use this directive to specify a terminating code for URL requests. Using the terminating code in a request causes Caching Proxy to evaluate only characters before the terminating code when processing the request and when evaluating whether the result is already cached. When more than one terminator code is defined, Caching Proxy compares incoming URLs against the terminator codes in the order in which they are defined in the ibmproxy.conf file.

Format

SignificantURLTerminator terminating_string   

Example

SignificantURLTerminator  &.

In this example, the two requests that follow are treated as identical.

http://www.exampleURL.com/tx.asp?id=0200&.;x=004;y=001
http://www.exampleURL.com/tx.asp?id=0200&.;x=127;y=034

Default

None

SMTPServer (Windows only)-- set an SMTP server for the sendmail routine

Use this directive to set the SMTP server used by the internal sendmail routine within the Caching Proxy for Windows. The following two directives must also be set for this routine: WebMasterEMail -- Set an e-mail address to receive select server reports and WebMasterSocksServer (Windows only)-- set a socks server for the sendmail routine.

Format

SMTPServer IP address or hostname of SMTP server

Example

SMTPServer mybox.com

Default

None

SNMP -- Enable and disable SNMP support

Use this directive to enable or disable SNMP support.

Format

SNMP   {on | off}

Default

SNMP off

SNMPCommunity -- Provide a security password for SNMP

Use this directive to define the password between the Web server Distributed Protocol Interface (DPI) subagent and the SNMP agent. The SNMP community name authorizes a user to view the performance variables monitored by SNMP for a specified community of servers. The system administrator defines which variables from which servers can be viewed when a password is entered. If you change the SNMP community name, be sure to also change the community name specified in the file /etc/snmpd.conf.

Format

SNMPCommunity name

Default

SNMPCommunity public

SSLCaching -- Enable caching for a secure request

Use this directive to cache content on a secure request when a reverse proxy is used. This directive configures caching for all connections to the proxy server, both client connections and connections with a back-end content server.

Note:
The SSL directives are not supported on SUSE Linux.

Format

SSLCaching {on | off}

Default

SSLCaching off

SSLCertificate -- Specify key labels for certificates

Use this directive to specify key labels that allow the proxy to determine which certificate to send to the client when Caching Proxy is acting as a single reverse proxy for multiple domains that offer their own SSL certificates and to instruct the proxy server to either retrieve or not retrieve a client-side PKI certificate for client authentication.

Using the SSLCertificate directive, Caching Proxy can distinguish between a certification authority (CA) issued certificate or a self-assigned certificate. However, by accepting any CA issued certificate (ClientAuthRequired option), using this directive can allow users who are not valid to gain access to the proxy server. When using the ClientAuthRequired option on the SSLCertificate directive, you can use the logical expression option to determine which valid users can access the SSL channel.

When an additional logical expression is added to the SSLCertificate directive, Caching Proxy extracts values from the client certificate and calculates the logical expression. If the expression is satisfied by the values in the client certificate, Caching Proxy grants the client use of the SSL connection; otherwise, the connection is shut down and closed.

Format

SSLCertificate serverIP/hostname CertificateLabel 
     [NoClientAuth | ClientAuthRequired logic-expression]
serverIP/hostname
You can specify an IP address (for example, 204.146.167.72) or you can specify a host name (for example, hostA.raleigh.ibm.com) for the server to which the SSL request is directed.
CertificateLabel
The name of the certificate which is to be used if client authentication is required for SSL requests directed to the designated IP address or host name.
[NoClientAuth | ClientAuthRequired logic-expression]
Instructions to the proxy server to either retrieve or not retrieve a client-side PKI certificate.

The logical expression option is valid only when used with the ClientAuthRequired option. When an additional logical expression is added to the SSLCertificate directive, Caching Proxy extracts values from the client certificate and calculates the logical expression. If the expression is satisfied by the values in the client certificate, Caching Proxy grants the client use of the SSL connection; otherwise, the connection is shut down and closed.

Examples

SSLCertificate www.abc.com ABCCert
SSLCertificate 204.146.167.72 intABCCert
SSLCertificate www.xyz.com XYZCert ClientAuthRequired
SSLCertificate www.xyz.com XYZCert ClientAuthRequired 
  CN="valid.user.common.name.pattern" && (L="accepted.location.pattern" || 
  C!="not.valid.country.pattern")

Default

None

SSLCryptoCard -- Specify the installed cryptographic card

This applies to reverse proxy configurations only.

Use this directive to tell the proxy server that there is a cryptographic card installed and to specify the card.

On AIX, to support the IBM 4960 PCI Cryptographic Accelerator Card, refer to PKCS11DefaultCert, PKCS11DriverPath, PKCS11TokenPassword -- Supports IBM 4960 PCI Cryptographic Accelerator Card (AIX only).

Format

SSLCryptoCard {rainbowcs | nciphernfast} {on | off}

Example

SSLCryptoCard rainbowcs on

Default

None

SSLEnable -- Specify listening on port 443 for secure requests

Use this directive to specify that the Caching Proxy listens on port 443 for secure requests.

Note:

Format

SSLEnable {on | off}

Default

SSLEnable off

SSLForwardPort -- Specify which port to address for HTTP SSL upgrades

Use this directive to specify the port to address for HTTP requests that the Caching Proxy upgrades to HTTPS requests by implementing SSL. Specify a port other than the main HTTP port 80 or the main SSL port 443.

Format

SSLForwardPort port number 	

Example

SSLForwardPort 8888

Default

None

SSLOnly -- Disable listener threads for HTTP requests

Use this directive to disable listener threads for standard HTTP requests (typically ports 80 and 8080) when SSL (typically port 443) is enabled.

Format

SSLOnly    {on | off}

Default

SSLOnly   off

SSLPort -- Specify HTTPS listening port other than default

Use this directive to specify the HTTPS listening port other than ibmproxy's default HTTPS port 443.

Note:

Format

SSLPort port value 	

Where the port value is an integer value greater than 0. Also the port value should be allowed by the operating system and should not be used by any other application.

Example

SSLPort 8443

Default

443

SSLTunneling -- Enable SSL tunneling

This applies to forward proxy configurations only.

Setting this directive on allows SSL tunneling to any port on the destination server. Setting this directive off allows SSL tunneling only to ports given in Proxy rules. If there are no Proxy rules for SSL tunneling, and the SSLTunneling directive is set to off, then SSL tunneling is not allowed. If the SSLTunneling directive is set to on, you must also enable the method CONNECT, using the directive Enable.

You should enable this directive if you are using Caching Proxy as a forward proxy. However, when using Caching Proxy as a reverse proxy, disabling this directive (default) protects against SSL tunneling vulnerability attacks.

For more information, see SSL tunneling.

Note:
Use the Proxy directive to enable SSL tunneling to a specific port on the destination host.

Format

SSLTunneling {on | off}

Default

SSLTunneling off

SSLVersion -- Specify the version of SSL

Use this directive to specify the version of SSL to use: V2, V3, or all versions. Set this directive to V2 if you are using servers that cannot support SSL Version 3.

Note:
The SSL directives are not supported on SUSE Linux.

Format

SSLVersion  {SSLV2 | SSLV3 | all} 

Default

SSLVersion SSLV3

SSLV2Timeout -- Specify the time to wait before a SSLV2 session expires

Use this directive to specify in seconds how long an SSL version 2 session waits with no activity before the session expires.

Note:
The SSL directives are not supported on SUSE Linux.

Format

SSLV2Timeout  seconds 

where seconds represents a value between 0 and 100.

Default

SSLV2Timeout 100

SSLV3Timeout -- Specify the time to wait before a SSLV3 session expires

Use this directive to specify in seconds how long an SSL version 3 session waits with no activity before it expires.

Note:
The SSL directives are not supported on SUSE Linux.

Format

SSLV3Timeout seconds

where seconds represents a value between 1 and 86400 seconds (which is 1 day in seconds).

Default

SSLV3Timeout 100

SuffixCaseSense -- Specify whether suffix definitions are case sensitive

Use this directive to specify whether you want the server to distinguish between uppercase and lowercase letters when file suffixes are compared to the suffix patterns on the AddClient, AddCharSet, AddType, AddEncoding, and AddLanguage directives. By default, the server does not distinguish between cases.

Format

SuffixCaseSense  {on | Off}

Default

SuffixCaseSense  Off

SupportVaryHeader -- Cache more than one variant of a resource based on the HTTP Vary header

Use this directive to allow Caching Proxy to cache more than one variant of a resource (URI) based on the HTTP Vary header.

When the SupportVaryHeader directive is enabled, the proxy forms a cache ID based on the URI and the selected header values in the client request.

The names of the selected headers are specified in the Vary header sent in a prior response from the server. If the server changes the set of selected header names for a resource, then all the previous cached objects for the resource are removed from the proxy's cache.

This directive can be used with the RegisterCacheIdTransformer directive (RegisterCacheIdTransformer -- Cache more than one variant of a resource based on the Cookie header).

When both directives are used, the proxy creates an internal Cache ID transformer based on the Vary header from the server and client's request header. In this way, the proxy can generate unique cache identifiers for different request and response pairs, even if the requested URIs are the same.

The cached objects of the same URI have their own default life time in the cache, depending on the Expire and Cache-Control headers in the requests/responses, or other configuration settings. If the Dynacache plug-in is used, all the multiple presentations associated to the same URI become not valid together in the proxy's cache.

Format

SupportVaryHeader {on | off}

Example

For this example, the following directives are enabled and configured in ibmproxy.conf as follows:

SupportVaryHeader on
RegisterCacheIdTransformer Cookie UserGroup

The client Guest accesses the proxy server with

URI [<code>] http://www.dot.com/group.jpg [</code>] 

and the following request/response:

GET /group.jpg HTTP/1.1 
Host: www.dot.com 
Cookie: UserGroup=Guest 
Accept-Language: en_US  

HTTP/1.1 200 
Server: my-server 
Vary: Accept-Language 
....... 

Next, client Admin accesses the proxy server with the same URI

http://www.dot.com/group.jpg

and the following request/response:

GET /group.jpg HTTP/1.1 
Host: www.dot.com 
Cookie: UserGroup=Admin  
Accept-Language: fr_FR  

HTTP/1.1 200 
Server: my-server 
Vary: Accept-Language 
....... 

As a result, if the responses are cacheable, the proxy server generates two different cache IDs:

1. CacheID(URI, "Guest", "en_US")
2. CacheID(URI, "Admin", "fr_FR")

The proxy server stores two different variants of the response from the server in the cache. Subsequently, when any client requests the resource (.../group.jpg), with either combination of language preference and user group values, the proxy server retrieves the appropriate variant of the resource from the cache and serves it.

Default

SupportVaryHeader off

TLSV1Enable -- Enable Transport Layer Secure protocol

Use this directive to enable the TLS version 1 protocol in SSL connections. After this directive is turned on, the SSL connection checks the TLS protocol first, then the SSLv3 protocol, and the SSLv2 protocol last.

Note:
This directive works with Internet Explorer and other browsers, but not with Netscape. (Netscape is not a recommended browser for use with Caching Proxy.)

Format

TLSV1Enable {on | off}

Example

TLSV1Enable on

Initial configuration setting

None

Transmogrifier -- Customize the Data Manipulation step

Use this directive to specify a customized application function that the server calls during the Data Manipulation step. This code provides three application functions:

You can have multiple Transmogrifiers active for each instance of the server.

Format

Transmogrifier /path/file:function_name:function_name:function_name
/path/file
Specifies the fully qualified file name of the compiled program, including the extension.
function_name
Specifies the name you give the application function within your program. You must supply the name of the open, write, and close functions.

Example

Transmogrifier /ics/bin/icsext05.so:open_data:write_data:close_data

Default

None

TransmogrifiedWarning -- Send warning message to client

Use this directive to send a message to the client informing it that the data:

Format

transmogrifiedwaning {yes|no} 

Default

Yes

TransparentProxy -- Enable transparent proxy on Linux

This applies to forward proxy configurations only.

For Linux systems only, use this directive to specify whether the server can run as a transparent proxy server.

When the TransparentProxy directive is set to on, the BindSpecific directive is ignored and defaults to off. Because most HTTP Traffic flows on Port 80, it is highly recommended that it is one of the configured ports.

Format

TransparentProxy  {on | off} 
Port 80

Default

TransparentProxy  off

If IPCHAIN firewall is used, enabling the directive is sufficient to successfully configure the transparent proxy. If IPTABLES firewall is used, then you need to add IPTABLES firewall rule manually.

If using IPTABLES firewall, when the TransparentProxy directive is enabled, and before starting the proxy server, run the following command to add the firewall rule into the IPTABLES:

iptables -t nat -A PREROUTING -i your-network-interface -p tcp --dport 80  -j 
  REDIRECT --to-port ibmproxy-listening-port  

Assuming that the firewall and the proxy server are on the same box, this rule instructs the IPTABLES firewall to redirect all TCP traffic designated for port 80 to the local proxy listening port. The rule can also be added in the IPTABLES configuration. This allows the rule to load automatically when the system restarts.

After starting transparent proxy, if you want to stop the Caching Proxy server, you must also issue the following command as root:

ibmproxy -unload

On Linux systems, this command removes the redirection firewall rules. If you do not issue this command after stopping the server, your machine will accept requests that are not destined for it.

UpdateProxy -- Specify the cache destination

Use this directive to specify which proxy server the cache agent updates. This is required when the cache agent needs to update a proxy server other than the local proxy server on which the cache agent is running. Optionally, you can specify the port.

Note:
On Linux and UNIX platforms, this directive is required for using the cache agent. If you are using only one machine for the proxy, specify the host name.

Although the cache agent can update the cache on another server, it cannot retrieve the cache access log from that machine. Therefore, if the UpdateProxy directive specifies a host other than the local host, the LoadTopCached directive is ignored.

Format

UpdateProxy fully_qualified_host_name_of_proxy_server

Example

UpdateProxy proxy15.ibm.com:1080

Default

None

UserId -- Specify the default user ID

Use this directive to specify the user name or number to which the server changes before accessing files.

If you change this directive, you must manually stop your server and then start it again for the change to take effect. The server does not recognize the change if you only restart it. (See Starting and stopping Caching Proxy.)

Note:
If you change the server defaults for the user ID, group ID, or log directory paths, create the new directories and update the permissions and ownership of the directories. To enable the server to write information to a user-defined log directory, set the permission for that directory as 755, and set the user-defined server user ID as the owner. For example, if you change the user ID of the server from the default to jdoe, and the default logs directory to server_root/account, then the server_root/account directory must have the permission 755 and be owned by jdoe.

Format

UserId  {ID_name | number} 

Default

AIX, Linux, Solaris: UserId nobody

HP-UX: UserId www

V2CipherSpecs -- List the supported cipher specifications for SSL Version 2

This directive lists the available cipher specification for SSL Version 2.

Note:
The SSL directives are not supported on SUSE Linux.

Format

V2CipherSpecs specification

Acceptable values are any combination of the following. None can be used twice.

Examples

Default

None (SSL is disabled by default.)

V3CipherSpecs -- List the supported cipher specifications for SSL Version 3

This directive lists available cipher specifications for SSL Version 3.

Note:
The SSL directives are not supported on SUSE Linux.

If the FIPSenable directive is set "on", the V3CipherSpecs directive will be ignored. For more information, see FIPSEnable -- Enable Federal Information Processing Standard (FIPS) approved ciphers for SSLV3 and TLS.

Format

V3CipherSpecs specification

Acceptable values include the following:

Examples

Default

None (SSL is disabled by default.)

WebMasterEMail -- Set an e-mail address to receive select server reports

Use this directive to set an e-mail address at which to receive select Caching Proxy reports, such as a notice 30 days prior to the expiration of an SSL certificate. On Linux and UNIX systems, a sendmail process must be running. For Windows systems, the sendmail process is built into the Caching Proxy, so no external mail server is required; however, two additional directives must be set: WebMasterSocksServer (Windows only)-- set a socks server for the sendmail routine and SMTPServer (Windows only)-- set an SMTP server for the sendmail routine.

Note:
This e-mail address is also used as the anonymous FTP password.

Format

WebMasterEMail webmastermailaddress

Example

WebMasterEmail webmaster@computer.com

Default

WebMasterEmail webmaster

WebMasterSocksServer (Windows only)-- set a socks server for the sendmail routine

Use this directive to set the socks server used by the internal sendmail routine within the Caching Proxy for Windows. The following two directives must also be set for this routine: WebMasterEMail -- Set an e-mail address to receive select server reports and SMTPServer (Windows only)-- set an SMTP server for the sendmail routine.

Format

WebMasterSocksServer IP address or hostname of socks server

Example

WebMasterSocksServer socks.mybox.com

Default

None

Welcome -- Specify the names of welcome files

Use this directive to specify the name of a welcome file that the server looks for to respond to requests that do not contain a specific file name. You can build a list of welcome files by putting multiple occurrences of this directive in the configuration file.

For requests that do not contain a file name or a directory name, the server always looks in the file root directory for a file that matches a name specified on a Welcome directive. If a match is found, the file is returned to the requester.

If the server finds more than one match between files in a directory and file names on Welcome directives, the order of the Welcome directives determines which file is returned. The server uses the Welcome directive closest to the beginning of the configuration file.

Format

Welcome file_name [server_IP_address | host_name]
file_name
Specifies the name of a file that you want to define as a welcome file.
[server_IP_address | host_name]
If you are using multiple IP addresses or virtual hosts, use this parameter to specify an IP address or a host name. The server uses the directive only for requests that come to the server on this IP address or for this host. For an IP address, this is the address of the server’s network connection, not the address of the requesting client.

You can specify an IP address (for example, 240.146.167.72), or you can specify a host name (for example, hostA.bcd.com).

This parameter is optional. Without this parameter, the server uses the directive for all requests, regardless of the IP address on which the requests come in or the host name in the URLs.

A wildcard character cannot be specified for a server's IP address.

Examples

Defaults

These defaults are in the order used by the default configuration:

Welcome Welcome.html
Welcome welcome.html
Welcome index.html
Welcome Frntpage.html