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.
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.)
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 |
This appendix provides the following information about each directive:
DirectiveName value
These are the original values coded in the default configuration file. Change only the parts of the configuration file that you want to be different from the defaults. A directive that has no default value initially coded appears in the file preceded by a comment marker (#). If you want to specify a value for the directive, remove the comment marker and add the value to the line in the configuration file.
The following list includes values that are accepted in the configuration file:
All entries are converted to seconds and added together.
When editing the configuration file, remember the following requirements:
The Caching Proxy directives follow.
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.
AcceptAnything {on | off}
AcceptAnything off
AcceptAnything on
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.
It is a good idea to remove old log files because they can use a significant amount of space on your hard drive.
AccessLog /directory_path/logfile_name
AccessLog /logs/accesslog
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.
AccessLogExcludeMethod method [...]
AccessLogExcludeMethod GET AccessLogExcludeMethod PUT AccessLogExcludeMethod POST AccessLogExcludeMethod DELETE AccessLogExcludeMethod GET PUT
None. The server includes in the access log the files and directories requested by all types of methods.
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.
AccessLogExcludeMimeType MIME_type [...]
AccessLogExcludeMimeType image/gif AccessLogExcludeMimeType text/html AccessLogExcludeMimeType image/gif text/html
None. The access log includes requests to the server for files and directories of all MIME types.
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.
AccessLogExcludeReturnCode range
AccessLogExcludeReturnCode 300
None. The access log includes all requests to the server, regardless of the code.
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.
AccessLogExcludeURL file_or_type [...]
AccessLogExcludeURL *.gif AccessLogExcludeURL /Freebies/* AccessLogExcludeURL *.gif /Freebies/*
None. The server logs requests for access to all files and directories.
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.
AccessLogExcludeUserAgent user_agent [...]
AccessLogExcludeUserAgent *Mozilla/2.0 AccessLogExcludeUserAgent *MSIE 5*
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.
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.
AddBlankIcon icon_URL alternative_text
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.
AddBlankIcon logo.gif logo
The default does not specify alternative text because the icon is blank.
Use this directive to specify an icon for representing a directory on a directory listing.
AddDirIcon icon_URL alternatIve_text
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.
AddDirIcon direct.gif DIR
Use this directive to bind files with a particular suffix to a MIME encoding type. This directive is seldom used.
AddEncoding .extension encoding
AddEncoding .qp quoted_printable
AddEncoding .Z x-compress
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.
AddIcon icon_URL alternative_text MIME_type_template
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.
AddIcon video_file.m.pm.gif MOV video/*
Numerous defaults are set for the AddIcon directive in the ibmproxy.conf configuration file.
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.
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.
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:
The sample.html.de file is assigned the following ranking:
If a value is not specified for q in the Accept-Language header, the default value is 1.0.
Use this directive to specify an icon for representing a parent directory on directory listings.
AddParentIcon icon_URL alternative_text
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.
AddParentIcon parent.gif UP
AddParentIcon dir-up.gif UP
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.
AddType .extension type/subtype encoding [quality[ character_set]]
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.
AddType .ps application/postscript 8bit 1.0 AddType *.* application/binary binary 0.3
AddType .bin application/octet-stream binary 0.8
Numerous default settings for the AddType directive are contained in the configuration file (ibmproxy.conf).
Use this directive to specify an icon for representing files with an unknown file type on a directory listing.
AddUnknownIcon icon_URL alternative_text
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.
AddUnknownIcon saywhat.gif unknown
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.
AdminPort port_number
AdminPort 2001
AdminPort 8008
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.
AggressiveCaching url_pattern
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:
None
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.
appendCRLFtoPost url_pattern
appendCRLFtoPost http://www.hosta.com/
None
Use this directive to specify the remote cache array to be shared by the servers.
ArrayName array_name
None
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.
Authentication type /path/file:function_name
Authentication BASIC /ics/api/bin/icsextpgm.so:basic_authentication
None
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.
Authorization request_template /path/file:function_name
Authorization /index.html /api/bin/icsextpgm.so:auth_url
None
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.
AutoCacheRefresh {on | off}
AutoCacheRefresh On
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.)
BindSpecific {on | off} [OutgoingSrcIp ip_addr | host_name]
BindSpecific Off
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.
BlockSize size
By default, there is no setting for BlockSize in the configuration file. (The default value is 8192.)
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.)
CacheAccessLog path/file
CacheAccessLog /absolute/path/logfile CacheAccessLog /logs/logfile
Use this directive to specify the cache algorithm that the server uses during garbage collection.
CacheAlgorithm {bandwidth | responsetime | blend}
CacheAlgorithm bandwidth
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.
CacheByIncomingUrl {on | off}
CacheByIncomingURL off
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.
CacheClean time_specification
CacheClean 2 weeks
CacheClean 1 month
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.
CacheDefaultExpiry URL_template expiration_time
CacheDefaultExpiry ftp:* 1 day CacheDefaultExpiry gopher:* 2 days CacheDefaultExpiry http:* 0 days
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.
CacheDev {raw_disk_partition | file}
AIX: CacheDev /dev/rlv02
HP-UX: CacheDev /dev/rdsk/c1t15d0
Linux: CacheDev /opt/IBMWTE/filecache1
Solaris: CacheDev /dev/rdsk/clt3d0s0
Windows: CacheDev \\.\E:
None
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.
CacheExpiryCheck {on | off}
CacheExpiryCheck On
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).
CacheFileSizeLimit maximum {B | K | M | G}
CacheFileSizeLimit 4000 K
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.
CacheLastModifiedFactor url factor
CacheLastModifiedFactor *://hosta/* off CacheLastModifiedFactor ftp://hostb/* 0.30 CacheLastModifiedFactor ftp://* 0.25 CacheLastModifiedFactor http://* 0.10 CacheLastModifiedFactor * 0.50
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.
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.
CacheLocalDomain {on | off}
CacheLocalDomain on
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.
CacheMatchLanguage {on | off} lang-prefer-distance-limit special-id-for-all-lang
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.
CacheMatchLanguage off
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.
CacheMaxExpiry URL lifetime
CacheMaxExpiry ftp:* 1 month CacheMaxExpiry http://www.santaclaus.np/* 2 days 12 hours
CacheMaxExpiry 1 month
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).
CacheMemory amount {B | K | M | G}
CacheMemory 64 M
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.
CacheMinHold http://www.cachebusters.com/* 1 hour
None
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.
CacheNoConnect {on | off}
CacheNoConnect Off
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.
CacheOnly url_pattern
CacheOnly http://realstuff/*
None
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
CacheQueries ALWAYS http://www.hosta.com/* CacheQueries PUBLIC http://www.hostb.com/*
None
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.
CacheRefreshInterval URL_pattern time_period
CacheRefreshInterval time_period
CacheRefreshInterval *.gif 8 hours CacheRefreshInterval 1 week
CacheRefreshInterval 2 weeks
Use this directive to specify when to start the cache agent. You can start the cache agent at a specific time.
CacheRefreshTime HH:MM
CacheRefreshTime 03:00
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.
CacheTimeMargin minimum_lifetime
CacheTimeMargin 10 minutes
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.
CacheUnused url_template time_length
CacheUnused ftp:* 3 weeks CacheUnused gopher:* 3 days 12 hours CacheUnused * 4 weeks
CacheUnused ftp:* 3 days CacheUnused gopher:* 12 hours CacheUnused http:* 2 days
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.
Caching {on | off}
Caching On
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.
CompressAge number_of_days
CompressAge 1
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.
CompressCommand command
CompressCommand tar -cf /logarchs/log%%DATE%%.tar %%LOGFILES%% ; gzip /logarchs/log%%DATE%%.tar CompressCommand tar -cf /logarchs/log%%DATE%%.tar %%LOGFILES%% ; compress /logarchs/log%%DATE%%.tar CompressCommand zip -q /logarchs/log%%DATE%%.zip %%LOGFILES%%
CompressCommand pkzip -q d:\logarchs\log%%DATE%%.tar %%LOGFILES%%
None
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.
CompressDeleteAge number_of_days
CompressDeleteAge 7
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.
You can enable the compression filter function by adding the following two directives in the ibmproxy.conf file:
CompressionFilterEnable /opt/ibm/edge/cp/lib/mod_z.sl CompressionFilterAddContentType type-1[,type-n]
CompressionFilterEnable /opt/ibm/edge/cp/lib/mod_z.so CompressionFilterAddContentType type-1[,type-n]
CompressionFilterEnable C:\Progra~1\IBM\edge\cp\Bin\mod_z.dll CompressionFilterAddContentType type-1[,type-n]
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.
None
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.
None
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.
None
Use this directive to defines the number of connection threads to be used for connection management.
ConnThreads number
ConnThreads 5
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.
ContinueCaching percentage
ContinueCaching 75
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.
DefinePicsRule "filter_name" {
DefinePicsRule "RSAC Example" {
Use this directive to associate a default protection setup with requests that match a template.
DefProt request_template setup_name [FOR server_IP_address | host_name]
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.
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.
A wildcard character cannot be specified for a server's IP address.
DefProt /secret/* /server/protect/setup1.acc
DefProt /secret/* SECRET-PROT
DefProt { AuthType Basic ServerID restricted PasswdFile /docs/etc/WWW/restrict.password GroupFile /docs/etc/WWW/restrict.group GetMask authors PutMask authors }
DefProt /secret/* CustomerA-PROT 0.67.106.79 DefProt /secret/* CustomerB-PROT 0.83.100.45
DefProt /secret/* CustomerA-PROT hostA.bcd.com DefProt /secret/* CustomerB-PROT hostB.bcd.com
None
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.
DelayPeriod {on | off}
DelayPeriod On
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.
DelveAcrossHosts {on | off}
DelveAcrossHosts Off
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.
DelveDepth number_of_levels
DelveDepth 2
Use this directive to specify whether the cache agent loads pages linked from cached URLs.
DelveInto {always | never | admin | topn}
DelveInto always
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.
DirBackgroundImage /path/file
DirBackgroundImage /images/corplogo.png DirBackgroundimage http://www.somehost.com/graphics/embossed.gif
None
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.
DirShowBytes {on | off}
DirShowBytes Off
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.
DirShowCase {on | off}
DirShowCase On
Use this directive to specify whether directory listings include the date each file was last modified.
DirShowDate {on | off}
DirShowDate On
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.
DirShowDescription {on | off}
DirShowDescription On
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.
DirShowHidden {on | off}
DirShowHidden On
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.
DirShowIcons {on | off}
DirShowIcons On
Use this directive to set the maximum number of characters to show in the description field on directory listings.
DirShowMaxDescrLength number_of_characters
DirShowMaxDescrLength 25
Use this directive to set the maximum number of characters that are used for file names on directory listings.
DirShowMaxDescrLength number_of_characters
DirShowMaxLength 25
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.
DirShowMinLength number_of_characters
DirShowMinLength 15
Use this directive to specify whether directory listings include the size of each file.
DirShowSize {on | off}
DirShowSize On
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.
Disable method
Disable PUT Disable DELETE Disable CONNECT
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.
DisInheritEnv environment_variable
DisInheritEnv PATH DisInheritEnv LANG
In this example, all environment variables except PATH and LANG are inherited by CGI programs.
None
Use this directive to specify whether the server looks up the host names of requesting clients.
DNS-Lookup {on | off}
The value you use affects the following things about how your server works:
DNS-Lookup Off
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.
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.
Enable GET Enable HEAD Enable POST Enable TRACE Enable OPTIONS
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.
EnableTcpNodelay {All | HTTP | HTTPS | None}
EnableTcpNodelay All
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.
Error request_template /path/file:function_name
Error /index.html /ics/api/bin/icsext05.so:error_rtns
None
Use this directive to specify the path and file name where you want the server to log internal errors.
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.
ErrorLog /path/logs_directory/file_name
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.
ErrorPage keyword /path/filename.html
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.
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:
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).
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.
Use this directive to specify the event log path and file name. The event log captures informational messages about the cache itself.
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.
EventLog /path/logs_directory/file_name
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.
Exec request_template program_path [Server_IP_address | host_name]
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.
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.
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.
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
Exec /cgi-bin/* /opt/ibm/edge/cp/server_root/cgi-bin/* Exec /admin-bin/* /opt/ibm/edge/cp/server_root/admin-bin/*
Exec server_root/cgi-bin/* Exec server_root/admin-bin/* Exec server_root/DOCS/admin-bin/*
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.
ExportCacheImageTo export_file_name
None
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.
ExternalCacheManager External_Cache_Manager_ID Maximum_Expiry_Time
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
None
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.
Fail request_template [Server_IP_address | host_name]
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.
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.
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
None
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.
FIPSEnable {on | off}
FIPSEnable off
Use this directive to instruct the proxy to use the SOCKS configuration file to determine the type of connection to make.
flexibleSocks {on | off}
flexibleSocks on
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.
FTPDirInfo {top | bottom | off}
FTPDirInfo top
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.
ftp_proxy full_URL [domain_name_or_template]
ftp_proxy http:// outer.proxy.server/
None
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.
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:
None
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.
Gc {on | off}
Gc On
Use this directive to specify a customized application you want the server to use for garbage collection.
GCAdvisor /path/file:function_name
GCAdvisor /api/bin/customadvise.so:gcadv
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.
GcHighWater percentage
GcHighWater 90
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.
GcLowWater percentage
GcLowWater 60
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.
gopher_proxy full_URL[domain_name_or_template]
gopher_proxy http://outer.proxy.server/
None
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.)
GroupId { group_name | group_number}
AIX: GroupId nobody
HP-UX: GroupId other
Linux:
Solaris: GroupId nobody
Use this directive to specify the name of the proxy server returned in the HTTP header
HeaderServerName name
None
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.
Hostname {name | IP address}
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.
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.
http_proxy full_URL[domain_name_or_template]
http://outer.proxy.server/
None
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.
HTTPSCheckRoot {on | off}
HTTPSCheckRoot on
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.
ICP_Address IP_address
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.
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.
ICP_MaxThreads number_of_threads
ICP_MaxThreads 5
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.
ICP_Peer hostname http_port icp_port
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
None
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.
ICP_Port port_number
ICP_Port 3128
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.
ICP_Timeout timeout_in_milliseconds
ICP_Timeout 2000
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.
IgnoreURL URL
IgnoreURL http://www.yahoo.com/ IgnoreURL http://*.ibm.com/*
IgnoreURL */cgi-bin/*
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.
imbeds {on | off | files | cgi | noexec} {SSIOnly | 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.
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.
imbeds on SSIOnly
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.
ImportCacheImageFrom import_file_name
None
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.
InheritEnv environment_variable
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.
None. By default, all environment variables are inherited by CGI programs.
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).
InputTimeout time
InputTimeout 3 mins 30 secs
InputTimeout 2 minutes
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.
JunctionReplaceUrlPrefix url_pattern_1 url_pattern_2
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.
None
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.
JunctionRewrite {on | on UseCookie | off}
JunctionRewrite off
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.
JunctionRewriteSetCookiePath cookie-name1 cookie-name2...
None
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.
JunctionSkipUrlPrefix url_pattern
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.
None
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.
KeepExpired {on | off}
KeepExpired off
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.
KeyRing filename
Windows: KeyRing c:\Program Files\IBM\edge\cp\\key.kdb
Linux and UNIX: KeyRing /etc/key.kdb
None
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.
KeyRingStash file_path
Windows: KeyRingStash c:\Program Files\IBM\edge\cp\key.sth
Linux and UNIX: KeyRingStash /etc/key.sth
None
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).
LimitRequestBody max_body_size {K | M | G}
LimitRequestBody 10 M
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.
LimitRequestFields number_headers
LimitRequestFields 32
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).
LimitRequestFieldSize max_hdr_length {B | K}
LimitRequestFieldSize 4096 B
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.
ListenBacklog number_of_requests
ListenBacklog 128
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.
LoadInlineImages {on | off}
LoadInlineImages on
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.
LoadTopCached number_of_pages
LoadTopCached 100
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.
LoadURL url
LoadURL http://www.ibm.com/
None
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.
Log request_template /path/file:function_name
Log /index.html /api/bin/icsextpgm.so:log_url
None
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.
LogArchive {Compress | Purge | none}
LogArchive Purge
Use this directive to specify the file format of the access log files.
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).
LogFileFormat common
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).
LogToGUI {on | off}
LogToGUI off
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.
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'
LogToSyslog Off
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.
Map request_template new_request [server_IP_address | host_name]
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.
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.
Map /stuff/* /good/stuff/*
Map /stuff/* /customerA/good/stuff/* 240.146.167.72 Map /stuff/* /customerB/good/stuff/* 0.83.104.45
Map /stuff/* /customerA/good/stuff/* hostA.bcd.com Map /stuff/* /customerB/good/stuff/* hostB.bcd.com
None
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.
MapQuery request_template new_request [server_IP_address | host_name]
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.
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.
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.
None
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.
MaxActiveThreads number_of_threads
MaxActiveThreads 100
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).
MaxContentLengthBuffer size
MaxContentLengthBuffer 100 K
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.
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).
MaxLogFileSize maximum {B | K | M | G}
MaxLogfileSize 128 M
If the directive is commented out, however, there is not a limitation on the size of the log file.
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.
MaxPersistRequest number
MaxPersistRequest 5
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.
MaxQueueDepth maximum_depth
MaxQueueDepth 250
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.
MaxRuntime {0 | maximum_time}
MaxRuntime 2 hours 10 minutes
MaxRuntime 2 hours
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.
MaxSocketPerServer num
MaxSocketPerServer 10
MaxSocketPerServer 5
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.
MaxURLs maximum_number
MaxURLs 2000
Use this directive to specify members of the arrays that are shared by the servers using remote cache access.
Member name { subdirective subdirective . . }
The following subdirectives are included:
Member bittersweet.chocolate.ibm.com { RCAAddr 127.0.0.1 RCAPort 6294 CacheSize 25G Timeout 500 milliseconds BindSpecific On ReuseAddr Off }
None
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.
Midnight /path/file:function_name
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.
NameTrans request_template /path/file:function_name [Server_IP_address | host_name]
A wildcard character cannot be specified for a server's IP address.
NameTrans /index.html /api/bin/icsextpgm.so:trans_url
None
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]
NoBG on
NoBG off
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.
NoCaching URL_pattern
NoCaching http://joke/*
None
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.
NoLog {host_name | IP_address} [...]
NoLog 128.0.* *.edu localhost.*
None
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.
no_proxy domain_name_or_template[,...]
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:
None
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:
NoCacheOnRange [on | off]
You can also enable NoCacheOnRange in a proxy mapping rule:
Proxy /not-cachable/* http://server.com/no-cachable-resources/* NoCacheOnRange
NoCacheOnRange off
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.
NoProxyHeader header
NoProxyHeader Referer:
None
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.
NumClients number
NumClients 4
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.
ObjectType request_template /path/file:function_name
ObjectType /index.html /api/bin/icsextpgm.so:obj_type
None
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.
OptimizeRuleMapping [on | off ]
OptimizeRuleMapping off
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).
OutputTimeout time
OutputTimeout 30 minutes
Use this directive to specify the directory containing the proxy autoconfiguration files generated by using the remote config PAC file form.
PacFilePath directory_path
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.
Pass request_template [file_path [server_IP_address | host_name]]
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.
This parameter is optional. If you do not specify a path, the request itself is used as the path.
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.
Pass /gooddoc/*
Pass /parts/* /customerA/catalog/* 240.146.167.72 Pass /parts/* /customerB/catalog/* 0.83.100.45
Pass /Admin/* /usr/lpp/internet/server_root/Admin/* Pass /Docs/* /usr/lpp/internet/server_root/Docs/* Pass /errorpages/* /usr/lpp/internet/server_root/pub/errorpages/* Pass /* /usr/lpp/internet/server_root/pub/*
Pass /Admin/* /opt/ibm/edge/cp/server_root/Admin/* Pass /Docs/* /opt/ibm/edge/cp/server_root/Docs/* Pass /errorpages/* /opt/ibm/edge/cp/server_root/pub/errorpages/* Pass /* /opt/ibm/edge/cp/server_root/pub/*
Pass /Admin/* /usr/lpp/internet/server_root/Admin/* Pass /Docs/* /usr/lpp/internet/server_root/Docs/* Pass /errorpages/* /usr/lpp/internet/server_root/pub/errporpages/* Pass /* /usr/lpp/internet/server_root/pub/*
Pass /Admin/* /opt/ibm/edge/cp/server_root/Admin/* Pass /Docs/* /opt/ibm/edge/cp/server_root/Docs/* Pass /errorpages/* /opt/ibm/edge/cp/server_root/pub/errorpages/* Pass /* /opt/ibm/edge/cp/server_root/pub/*
Pass /icons/* C:\Program Files\IBM\edge\cp\icons\* Pass /Admin/* C:\Program Files\IBM\edge\cp\Admin\* Pass /Docs/* C:\Program Files\IBM\edge\cp\Docs\* Pass /erropages/* C:\Program Files\IBM\edge\cp\pub\errorpages\* Pass /* C:\Program Files\IBM\edge\cp\pub\*
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.
PersistTimeout time
PersistTimeout 4 seconds
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.
PICSDBLookup /path/file:function_name
PICSDBLookup /api/bin/icsext05.so:get_pics
None
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.
PidFile path_to_pid_file_info
PidFile /usr/pidinfo
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.
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.
PKCS11DefaultCert MyDefaultCertInTheToken PKCS11DriverPath /usr/lib/pkcs11/PKCS11_API.so PKCS11TokenPassword MyPasswordToOpenTheToken
None
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.
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.
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.)
Port 80
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.
PostAuth /path/file:function_name
AuthExit /ics/api/bin/icsext05.so:post_exit
None
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.
PostExit /path/file:function_name
PostExit /ics/api/bin/icsext05.so:post_exit
None
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.
PreExit /path/file:function_name
PreExit /ics/api/bin/icsext05.so:pre_exit
None
Use this directive to activate protection setup rules for requests that match a template.
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.
This parameter can take the following forms:
Protect request_template [setup_file | label[ [FOR Server_IP_address | host_name]
Protect request_template [FOR Server_IP_address | hhost_name] subdirective value subdirective value . . . }
The following parameters are used:
This parameter is optional. If it is omitted, the protection setup is defined by the most recent DefProt directive that contains a matching template.
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.
These examples use IP addresses. If the server receives requests that begin with /secret/ or /topsecret/, it activates a different protection setup for the request, based on the IP address of the network connection that request comes in on.
Protection BUS-PROT { UserID busybody GroupID webgroup AuthType Basic ServerID restricted PasswdFile /docs/WWW/restrict.pwd GroupFile /docs/WWW/restrict.grp GetMask authors PutMask authors } DefProt /secret/* /server/protect/setup1.acc Protect /secret/scoop/* Protect /secret/business/* BUS-PROT Protect /topsecret/* { AuthType Basic ServerID restricted PasswdFile /docs/WWW/restrict.pwd GroupFile /docs/WWW/restrict.grp GetMask topbrass PutMask topbrass } Pass /secret/scoop/* /WWW/restricted/* Pass /secret/business/* /WWW/confidential/* Pass /topsecret/* /WWW/topsecret/*
Protect /secret/* CustomerA-PROT FOR 0.67.106.79 Protect /secret/* CustomerB-PROT FOR 0.83.100.45 Protect /topsecret/* 0.67.106.79 { AuthType Basic ServerID restricted PasswdFile /docs/WWW/customer-A.pwd GroupFile /docs/WWW/customer-A.grp GetMask A-brass PutMask A-brass } Protect /topsecret/* 0.83.100.45 { AuthType Basic ServerID restricted PasswdFile /docs/WWW/customer-B.pwd GroupFile /docs/WWW/customer-B.grp GetMask B-brass PutMask B-brass }
Protect http://host1/* proxy-prot
Protect /secret/* CustomerA-PROT FOR hostA.bcd.com Protect /secret/* CustomerB-PROT FOR hostB.bcd.com Protect /topsecret/* hostA.bcd.com { AuthType Basic ServerID restricted PasswdFile /docs/WWW/customer-A.pwd GroupFile /docs/WWW/customer-A.grp GetMask A-brass PutMask A-brass } Protect /topsecret/* hostB.bcd.com { AuthType Basic ServerID restricted PasswdFile /docs/WWW/customer-B.pwd GroupFile /docs/WWW/customer-B.grp GetMask B-brass PutMask B-brass }
By default, protection is provided for the Configuration and Administration forms by a Protect directive with a request template of /admin-bin/*.
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.
Protection label_name { subdirective value subdirective value . . . }
See Protection subdirectives -- Specify how a set of resources is protected for descriptions of the protection subdirectives.
Protection NAME-ME { AuthType Basic ServerID restricted PasswdFile /WWW/password.pwd GroupFile /WWW/group.grp GetMask groupname PutMask groupname }
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 }
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.
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.
AuthType Basic
Use this Protection subdirective to specify user names, groups, and address templates authorized to make DELETE requests to a protected directory.
DeleteMask authors,(niceguy,goodie)@45.96.3.1,128.0.*.*
Use this Protection subdirective to specify user names, groups, and address templates authorized to make GET requests to a protected directory.
GetMask authors,(niceguy,goodie)@45.96.3.1,128.0.*.*
GetMask All@(*)
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:
GroupFile /docs/etc/WWW/restrict.group
Use this subdirective to specify user names, groups, and address templates authorized to make HTTP requests that are not covered by other mask subdirectives.
Mask authors,(niceguy,goodie)@45.96.3.1,128.0.*.*
MASK WEBADM,webadm
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:
PasswdFile /docs/etc/WWW/restrict.password
PasswdFile "c:\test this\admin.pwd"
For a secure server, use this Protection subdirective to specify users, groups, and address templates authorized to make POST requests to a protected directory.
PostMask authors,(niceguy,goodie)@45.96.3.1,128.0.*.*
Use this Protection subdirective to specify users, groups, and address templates authorized to make PUT requests to a protected directory.
PutMask authors,(niceguy,goodie)@45.96.3.1,128.0.*.*
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:
ServerID restricted
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:
This applies to reverse proxy configurations only.
This option instructs Caching Proxy to maintain a one-to-one mapping between the client-side socket and the outgoing socket. This option is useful for some applications, such as connection-based authentication, that need the proxy to keep the server-side socket alive and reuse the socket for the requests coming from same client-side socket.
If the proxy rule is matched, this option instructs the proxy not to cache the corresponding responses.
If the proxy rule is matched and there is a Range header in the request, this option instructs the proxy not to cache the corresponding response. For more information, refer to NoCacheOnRange -- Specify no caching for Range requests.
This applies to reverse proxy configurations only.
Use this option if the junction rewrite plug-in is enabled. This option does not allow the proxy to rewrite the corresponding responses if the incoming URL is matched. For more information, refer to Enable junction rewrite (optional) and Define the junction with the JunctionPrefix option (recommended method).
This applies to reverse proxy configurations only.
Use this option if the junction rewrite plug-in is enabled. Instead of inferring the junction prefix from the first URL pattern in the proxy rule, the option explicitly declares the junction rewrite prefix. For more information, refer to Enable junction rewrite (optional) and Define the junction with the JunctionPrefix option (recommended method).
Proxy request_template target_server_path [[ip]:port] [UseSession | NoCaching | NoCacheOnRange | NoJunction | JunctionPrefix:/url_prefix]
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/* .
None.
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.
ProxyAccessLog path/file
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.
ProxyAdvisor /path/file:function_name
ProxyAdvisor /api/bin/customadvise.so:proxyadv
None
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.
ProxyForwardLabels {on | off}
ProxyForwardLabels Off
Use this directive to generate a From: header. This is typically used to give an e-mail address of the proxy administrator.
ProxyFrom e-mail_address
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 |
None
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.
ProxyIgnoreNoCache {on | off}
ProxyIgnoreNoCache off
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.
ProxyPersistence {on | off}
ProxyPersistence on
Use this directive to specify whether the proxy forwards the IP address of the client to the destination server.
ProxySendClientAddress {Client_IP: | OFF}
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 |
None
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.
ProxyUserAgent product_name/version
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 |
None
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.
ProxyVia {Full | Set | Pass | Block}
ProxyVia Pass
ProxyVia Full
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.
ProxyWAS request_template target_server_path [[ip]:port] [UseSession | NoCaching | NoCacheOnRange | NoJunction | JunctionPrefix:/url_prefix]
None
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.
PureProxy {on | off}
PureProxy on
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.
PurgeAge number
PurgeAge 7
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.
PurgeSize number_of_MB
PurgeSize 0
Use this directive to specify the name and location of the Remote Cache Access configuration file.
RCAConfigFile /etc/file_name
RCAConfigFile /etc/user2rca.conf
RCAConfigFile /etc/rca.conf
Use this directive to specify the number of threads working on an RCA port.
RCAThreads number_of_threads
RCAThreads 50
MaxActiveThreads x [(ArraySize -1) / (2 x ArraySize -1)]
Use this directive to specify the time limit allowed without network activity before a connection is canceled.
ReadTimeout time
ReadTimeout 5 minutes
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.
Redirect request_template URL [server_IP_address | host_name]
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 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.
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.
Redirect /chief/stuff/* http://www.other.org/wahoo/*
Redirect /stuff/* http://www.chief.org/wahoo/* 240.146.167.72 redirectcode: 302 Redirect /stuff/* http://www.dawg.com/pound/* 0.83.100.45 redirectcode: 302
Redirect /stuff/* http://www.chief.org/wahoo/* hostA.bcd.com Redirect /stuff/* http://www.dawg.com/pound/* hostB.bcd.com
None
Use this directive to allow Caching Proxy to cache more than one variant of a resource (URI) based on the Cookie header.
For more information, see SupportVaryHeader -- Cache more than one variant of a resource based on the HTTP Vary header.
RegisterCacheIdTransformer Cookie cookie-name
The cookie-name is the name in the Cookie header in the client's request.
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.
None
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.
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.
ReversePass http://backend.company.com:9080/* http://edge.company.com/*The port 9080 is the default port for Application Service at the Edge. This type of request might be generated if the origin application server returned a 3xx code to the client.
ReversePass http://edge.company.com:9080/* http://edge.company.com/*
None
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.
RewriteSetCookieDomain domain_pattern1 domain_pattern2
RewriteSetCookieDomain .internal.com .external.com
None
This applies to reverse proxy configurations only.
This directive enables or disables RTSP redirection. Options are on or off.
RTSPEnable {on | off}
RTSPEnable on
None
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]
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
None
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
rtsp_proxy_threshold 5
None
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.
rtsp_url_list_size size_of_list
rtsp_url_list_size 8192
None
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.
RuleCaseSense {on | off}
RuleCaseSense on
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).
ScriptTimeout timeout
ScriptTimeout 5 minutes
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.
SendHTTP10Outbound url_pattern
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:
None
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.
SendRevProxyName {yes | no}
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.
ServerConnGCRun time_interval
ServerConnGCRun 2 minutes
ServerConnGCRun 2 minutes
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.
ServerConnPool {on | off}
ServerConnPool off
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.
ServerConnTimeout time-spec
ServerConnTimeout 30 seconds
ServerConnTimeout 10 seconds
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.
ServerInit /path/file:function_name [initialization_string]
ServerInit /ics/api/bin/icsext05.so:svr_init
None
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.
ServerRoot directory_path
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.
ServerTerm /path/file:function_name
ServerTerm /ics/api/bin/icsext05.so:shut_down
None
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.
Service request_template/path/file:function_name [server_IP_address | host_name]
A wildcard character cannot be specified for a server's IP address.
Service /index.html /ics/api/bin/icsext05.so:serve_req Service /cgi-bin/hexcalc* /ics/api/calculator:HEXcalc*
None
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.
SignificantURLTerminator terminating_string
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
None
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.
SMTPServer IP address or hostname of SMTP server
SMTPServer mybox.com
None
Use this directive to enable or disable SNMP support.
SNMP {on | off}
SNMP off
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.
SNMPCommunity name
SNMPCommunity public
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.
SSLCaching {on | off}
SSLCaching off
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.
SSLCertificate serverIP/hostname CertificateLabel [NoClientAuth | ClientAuthRequired logic-expression]
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.
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")
None
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).
SSLCryptoCard {rainbowcs | nciphernfast} {on | off}
SSLCryptoCard rainbowcs on
None
Use this directive to specify that the Caching Proxy listens on port 443 for secure requests.
SSLEnable {on | off}
SSLEnable off
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.
SSLForwardPort port number
SSLForwardPort 8888
None
Use this directive to disable listener threads for standard HTTP requests (typically ports 80 and 8080) when SSL (typically port 443) is enabled.
SSLOnly {on | off}
SSLOnly off
Use this directive to specify the HTTPS listening port other than ibmproxy's default HTTPS port 443.
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.
SSLPort 8443
443
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.
SSLTunneling {on | off}
SSLTunneling off
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.
SSLVersion {SSLV2 | SSLV3 | all}
SSLVersion SSLV3
Use this directive to specify in seconds how long an SSL version 2 session waits with no activity before the session expires.
SSLV2Timeout seconds
where seconds represents a value between 0 and 100.
SSLV2Timeout 100
Use this directive to specify in seconds how long an SSL version 3 session waits with no activity before it expires.
SSLV3Timeout seconds
where seconds represents a value between 1 and 86400 seconds (which is 1 day in seconds).
SSLV3Timeout 100
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.
SuffixCaseSense {on | Off}
SuffixCaseSense Off
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.
SupportVaryHeader {on | off}
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.
SupportVaryHeader off
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.
TLSV1Enable {on | off}
TLSV1Enable on
None
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.
Transmogrifier /path/file:function_name:function_name:function_name
Transmogrifier /ics/bin/icsext05.so:open_data:write_data:close_data
None
Use this directive to send a message to the client informing it that the data:
transmogrifiedwaning {yes|no}
Yes
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.
TransparentProxy {on | off} Port 80
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.
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.
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.
UpdateProxy fully_qualified_host_name_of_proxy_server
UpdateProxy proxy15.ibm.com:1080
None
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.)
UserId {ID_name | number}
AIX, Linux, Solaris: UserId nobody
HP-UX: UserId www
This directive lists the available cipher specification for SSL Version 2.
V2CipherSpecs specification
Acceptable values are any combination of the following. None can be used twice.
None (SSL is disabled by default.)
This directive lists available cipher specifications for SSL Version 3.
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.
V3CipherSpecs specification
Acceptable values include the following:
None (SSL is disabled by default.)
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.
WebMasterEMail webmastermailaddress
WebMasterEmail webmaster@computer.com
WebMasterEmail webmaster
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.
WebMasterSocksServer IP address or hostname of socks server
WebMasterSocksServer socks.mybox.com
None
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.
Welcome file_name [server_IP_address | host_name]
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.
Welcome CustomerA.html 0.67.106.79 Welcome CustomerB.html 0.83.100.45
Welcome CustomerA.html hostA.bcd.com Welcome CustomerB.html hostB.bcd.com
These defaults are in the order used by the default configuration:
Welcome Welcome.html Welcome welcome.html Welcome index.html Welcome Frntpage.html