Version 1.0.3
Document Number 0000-0000-00
0000000
First Edition (March 2001)
This edition applies to:
and to all subsequent releases and modifications until otherwise indicated in new editions.
This softcopy version is based on the printed edition of this book. Some formatting amendments have been made to make this information more suitable for softcopy.
Order publications through your IBM representative or through the IBM branch office serving your locality.
© Copyright International Business Machines Corporation 2001. All rights reserved.
Note to U.S. Government Users -- Documentation related to restricted rights -- Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule contract with IBM Corp.
IBM WebSphere Edge Server README
The IBM WebSphere Edge Server v1.0.3 README replaces previous IBM WebSphere Edge Server README documents. This document highlights important information and requirements that apply to IBM WebSphere Edge Server components. This document also includes information on updates made to the product since the IBM WebSphere Edge Server v1.0 General Availability (GA) release.
IBM WebSphere Edge Server v1.0.3 includes IBM Web Traffic Express v3.6 (the Caching Proxy) and IBM Network Dispatcher v3.6 (the Load Balancer). New features are available in both components. The Product notes section of this document contains details of these new features and of other features that have been added since the IBM WebSphere Edge Server v1.0 General Availability release; see Product notes.
New features include both functional enhancements and plug-in modules. Functional enhancements are new functions written directly into the core of the Caching Proxy program. New features are enabled by setting the appropriate directives within the proxy server configuration file, ibmproxy.conf. Plug-in modules are separate programs that are typically invoked as preexits or routine callouts from the Caching Proxy API. Directives within the proxy server configuration file enable these plug-ins. (Each plug-in has different requirements; see Product notes for individual feature documentation.)
The Caching Proxy now supports the Solaris 8 operating system running in 32-bit mode. See Supported system types for details.
The Caching Proxy can now retrieve a client-side PKI certificate through an SSL session. See Client-side certificate authentication for details.
Caching Proxy administrators can now disable listener threads for standard HTTP requests when SSL is enabled. See Disabling listener threads when SSL is enabled for details.
The Caching Proxy now supports the use of IP ranges in protection masks. See Use of IP ranges in protection masks for details.
The Caching Proxy now allows POST and PUT requests to be handled over persistent connections. See Requests over persistent connections for details.
The Caching Proxy can now cache JavaServer Pages(TM) (JSP) and servlet responses generated from a WebSphere Application Server that is configured with a Caching Proxy plug-in module. See JSP and servlet response caching for details.
The Caching Proxy can now authenticate clients using an LDAP database. See LDAP authorization plug-in for details.
The Caching Proxy can now query other Internet Caching Protocol (ICP) compliant caches in search of HTML pages and other cacheable resources. See ICP plug-in for details.
The Caching Proxy now includes a plug-in that supports the use of the SurfControl database to filter URLs. See CyberPatrol filtering plug-in for details.
The following new features are available in the Load Balancer.
The Load Balancer supports Java 1.3 on all platforms. There is no longer support for Java 1.1.x. This feature applies to the Dispatcher, CBR, and ISS components. See Java 1.3 support for details.
The Load Balancer supports 1 Gigabit Ethernet NICs (network interface cards) on all supported platforms. This feature applies to the Dispatcher, CBR, and ISS components. See Gigabit Ethernet support for details.
The Load Balancer now supports quad-port Ethernet NICs on all supported platforms. See Quad-port Ethernet support for details.
In addition to supporting Solaris Version 2.6 and Solaris Version 7 (32-bit mode), the Load Balancer now also supports Solaris 8 (32-bit mode). This feature applies to the Dispatcher, CBR, and ISS components. See Solaris 8 support for details.
In addition to supporting Red Hat Linux v6.1, the Load Balancer now also supports Red Hat Linux v6.2 (Linux kernel version 2.2.16-3, as well as any additional fixes to 2.2.16). This feature applies to the Dispatcher and CBR components. See Red Hat Linux 6.2 support for details.
The Load Balancer now fully supports collocation and high availability simultaneously for Red Hat Linux. This feature applies to the Dispatcher component. See Collocated server support for Red Hat Linux for details.
The Load Balancer now supports the reserved bandwidth rule and the shared bandwidth rule, allowing customers to manage the bandwidth capacity of outbound traffic for sets of servers within the configuration. This feature applies to the Dispatcher component. See Capacity utilization and bandwidth rules for details.
This enhancement allows you to choose to measure either a rule's condition across the servers within the rule or to measure a rule's condition across all servers within the port. This feature applies to the Dispatcher component. See Server evaluation option for details.
The Load Balancer can now load-balance packets to servers (such as OS/390) that have multiple server addresses associated with one MAC address. GRE is implemented as part of the Load Balancer's WAND (wide area Network Dispatcher) feature. This feature applies to the Dispatcher component. See GRE support for details.
The Load Balancer now allows the customer to set the timeout values at which the advisor detects that a server has failed. This feature applies to the Dispatcher and CBR components. See Advisor fast-failure detection for details.
The Load Balancer extends the server quiesce function to recognize existing connections that have the affinity feature and allows the quiesced server to accept subsequent connections from those clients before "stickytime" expires. This feature applies to the Dispatcher and CBR components. See Quiesce enhancement for sticky connections for details.
This enhancement applies to two-tiered ISS configuration where an ISS DNS monitor load balances across a lower tier of Load Balancer machines. Using the self advisor, the Load Balancer delivers enhanced load status information on back-end servers to the ISS DNS monitor in order to make more appropriate load-balancing decisions. This feature applies to the Dispatcher and ISS components. See Enhanced ISS load balancing for details.
The Load Balancer extends CBR to support SSL from the proxy to the server, allowing for a complete SSL connection from the client to the server. This feature applies to the CBR (with the Caching Proxy) component. See SSL proxy-to-server support for details.
This section contains details on updates made to the product since the General Availability (GA) release of IBM WebSphere Edge Server v1.0. Both the caching proxy component and the load balancing component have been updated. This section also includes information on limitations in the current version of the product. The notes in this section supplement those included in the "Product Notes" chapter of IBM WebSphere Edge Server for Multiplatforms Getting Started; some notes supersede information provided in that book. See that document for additional information.
To access an online version of IBM WebSphere Edge Server for Multiplatforms Getting Started and to find the latest information about this product, refer to the following IBM Web site:
http://www.ibm.com/software/webservers/edgeserver
These notes apply either to the WebSphere Edge Server as an integrated product suite and therefore affect all product components, or they apply to the Edge Server graphical installation program, InstallShield Wizard.
Upgrade Edge Server to version 1.0.3 (Caching Proxy v3.6 and Load Balancer v3.6) from any of the following previous versions:
You must update prerequisite software before upgrading the Load Balancer to version 3.6. See Load Balancer product notes.
Downloading the WebSphere Edge Server trial code does not automatically install the trial license for the Edge Server's load balancing component. A license request is generated automatically when you register or sign in for the download. The license file is e-mailed to the address in the registration profile and must be installed manually. Instructions for installing the trial license are included in the mail message.
AIX update is required to display simplified Chinese
On AIX Version 4.3.3, a software correction is needed to correctly display simplified Chinese (the zh_CN locale) in the Edge Server graphical installation interface (InstallShield Wizard). The correction provides a 13-point font that is used in the installation interface. To obtain the software, connect to the Web site http://techsupport.services.ibm.com/support/rs6000.support/downloads. Use the search utility at the top of the page to find the software patch that applies to Authorized Program Analysis Report (APAR) IY07374 by typing IY07374 in the first field, using the pull-down menu in the second field to select SW Fix Database by APAR as the database in which to search, and selecting Go. Then, follow the directions provided to download and install the software fix.
Custom installation fails if installed components are selected
The InstallShield Wizard custom method of installing Load Balancer components fails on Linux-based machines if components that are already installed on the system are selected. To install successfully using the custom installation option, select only items that are not yet installed on the system. For example, if you have previously installed the CBR Runtime component, the CBR administration component, and the CBR license on your Linux system, a custom installation fails if you select CBR Runtime, Dispatcher Administration, and Dispatcher License.
InstallShield Wizard sometimes fails on Japanese Red Hat platforms
The Edge Server graphical installation (InstallShield Wizard) sometimes fails on Red Hat Linux 6.1J and 6.2J with the Japanese locale setting ja_JP.eucJP. Use an alternative method to install the Caching Proxy software on these platforms. One alternative method for installing the Caching Proxy software for the Japanese locale is to use the installation script, install.sh, with the -locale option, as follows.
/mnt/cdrom/linux/wte/install.sh -locale ja_JP
(If you have mounted the CD-ROM drive in a path other than /mnt/cdrom/, specify your CD path instead.) Complete instructions for installing the Caching Proxy without using the InstallShield Wizard are available in the Web Traffic Express User's Guide.
The Caching Proxy is not always running after Edge Server installation
After the WebSphere Edge Server InstallShield Wizard installation of the Caching Proxy, the ibmproxy daemons are not always left running on Linux-based machines. To solve this problem, start the process manually as documented in the Web Traffic Express User's Guide, or restart the machine to start it automatically.
No install.log file on Windows platforms
No install.log file is created during the InstallShield Wizard installation on Windows platforms. On UNIX platforms, this log file is created to capture information about the installation process.
Scrollbar error message
On all UNIX-based platforms, the following warning message can possibly appear during the Edge Server installation process.
Warning: Name: HorScrollBar Class: XmScrollBar The specified scrollbar value is greater than the maximum scrollbar value minus the scrollbar slider size.
The message does not affect the installation and can be ignored.
The following documentation corrections apply to the IBM WebSphere Edge Server Getting Started:
With increased Tivoli requirements, Edge Server is not Tivoli ready. The Tivoli README file that is included with the load balancing component refers to the Tivoli readiness of previous Load Balancer products (version 3.0 and earlier). Its existence does not imply that Edge Server is currently Tivoli ready.
You can obtain Caching Proxy and Load Balancer updates in the form of Program Temporary Fixes (PTFs).
You can download PTFs from the IBM WebSphere Software Web site at http://www.ibm.com/software/webservers/edgeserver/support.html. In the Support downloads area, select a WebSphere Edge Server corrective service release and follow the link to the corrective service download site.
These notes apply to the caching proxy component of WebSphere Edge Server.
Additional Linux systems supported
The Caching Proxy now provides support for Red Hat Linux 6.2 (kernel 2.2.16) and SuSE Linux 6.4 (kernel 2.2.14).
Solaris 8 supported
The Caching Proxy now supports the Solaris 8 operating system running in 32-bit mode. Only SPARC and Ultra-SPARC chipsets are supported. Solaris 8 on an x86 chipset is not supported.
Forward support for AIX
The Caching Proxy provides support for AIX 4.3.2 and higher.
This new function permits the Caching Proxy to retrieve a client-side PKI certificate through an SSL session. This certificate is then used to authenticate the client. Requiring clients to present a PKI certificate increases server security by guaranteeing the authentication of the client. Use the SSLCertificate directive to instruct the proxy server to either retrieve or not retrieve a client-side PKI certificate. See WTE Directives for details.
This new function permits Caching Proxy administrators to disable listener threads for standard HTTP requests (typically port 80 and 8080) when SSL (typically port 443) is enabled. Running active HTTP listener threads can possibly create an insecure site on a server performing secure transactions. The ability to turn off these listener threads enhances server security. Use the SSLOnly directive to disable listener threads for standard HTTP requests when SSL is enabled. See WTE Directives for details.
This new function adds the ability to use IP ranges in protection masks. Administrators can now more easily configure the Caching Proxy to authenticate requests from specified IP addresses and not authenticate requests from others, avoiding the need to create very large protection rule files that might adversely impact proxy performance. For example, specify the following to authenticate all requests from 9.38.(100-192)/202/203.(0-255) and to pass all other requests.
MASK ALL@"9.38.[100-192,202,203].[0-255]", @"9.38.[0-99],193-201,204-255]. [0-255]",@"[0-8,20-255].[0-37,39-255].[0-255].[0-255]"
In this example, note that brackets enclose ranging; quotation marks enclose the ranging IP template, and spaces are not allowed in the ranging IP template. Note that the directive must not contain line breaks.
The Caching Proxy now allows POST and PUT requests to be handled over persistent connections. Previously, only GET requests were handled over persistent connections.
The JSP caching function enables the Caching Proxy to cache JavaServer Pages (JSP) and servlets generated from a WebSphere Application Server that is configured with a Caching Proxy plug-in module. The Caching Proxy pulls the JSP results from the application server's dynamic cache. Dynamic content can then be cached on the edge of the network, freeing the content host from repeatedly retrieving files from the application server in order to satisfy requests for it from different clients. The caching of dynamically generated content offers the following benefits:
Currently, the external cache interface exports only fully composed public pages. Private pages are not cached by the proxy. For example, a dynamically generated page from a public site that lists the current weather forecast can be exported by the WebSphere Application Server and cached by the Caching Proxy; on the other hand, a dynamically generated page listing the contents of a user's shopping cart cannot be cached by the Caching Proxy.
Application Server configuration
The WebSphere Application Server communicates with the Caching Proxy using an external cache adapter (ECA). Enable the proxy's ECA on the application server by adding an externalCacheGroups entry to the WebSphere Application Server dynacache.xml file. Note that one application server can be configured to serve multiple proxy servers.
For example, if the application server with domain XYZ-1 is used to serve two proxy servers, abc.xcompany.com and def.xcompany.com, then add the following entry to the dynacache.xml file on the application server.
<externalCacheGroups>
<group id="IBM-WTE-XYZ-1" type="shared">
<member address="abc.xcompany.com;def.xcompany.com"
adapterBeanName="com.ibm.wte.WteAdapter"/>
</group>
</externalCacheGroups>
The WebSphere Application Server serves only proxy servers whose addresses match a member address in the externalCacheGroups entry in the dynacache.xml file.
For additional information on the dynamic caching functionality in the WebSphere Application Server and for supported platforms and system requirements, see the WebSphere Application Server Web site, http://www.ibm.com/software/webservers/appserv.
Caching Proxy configuration
The JSP caching feature is configured by editing the proxy configuration file, ibmproxy.conf. A Service directive is used to enable the JSP caching function. To create this directive, either manually edit the ibmproxy.conf file, or, if the proxy server is already running, connect to the Configuration and Administration forms with an Internet browser and open the API Request Processing form (select Server Configuration, Request Processing, and API Request Processing). Each directive must appear on a single line in the proxy configuration file, regardless of whether these examples contain line breaks for clarity.
Note that 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 plug-in 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 plug-in.
Service /WES_External_Adapter /opt/IBMWTE/usr/internet/lib/plugins/ dynacache/libdyna_plugin.o:exec_dynacmd
Service /WES_External_Adapter /opt/IBMWTE/usr/internet/lib/plugins/ dynacache/libdyna_plugin.so:exec_dynacmd
Service /WES_External_Adapter /usr/lib/libdyna_plugin.so:exec_dynacmd
Service /WES_External_Adapter C:\Program Files\IBM\WTE\bin\plugins\ dynacache\dyna_plugin.dll:exec_dynacmd
If you have installed the Caching Proxy software in a directory other than the default, substitute your installation path.
Each Caching Proxy must be configured to recognize the source of the HTML (WebSphere Application Server) by adding the ExternalCacheManager directive to the ibmproxy.conf file. (See WTE Directives for more details.) For the previous example, add the following entry to each proxy's ibmproxy.conf file.
ExternalCacheManager IBM-WTE-XYZ-1 20 seconds
The Caching Proxy caches only contents from a WebSphere Application Server whose group ID matches an ExternalCacheManager entry in the ibmproxy.conf file.
Servlet configuration
The dynamic cache (on the WebSphere Application Server) operates based on entries in its servletcache.xml file. All servlets for which dynamic caching is enabled have entries in the servletcache.xml file. For a servlet's results to be cachable by the proxy cache, the servlet entry must be marked as externally cachable. This is done by defining an externalcache ID in the servlet's entry. The externalcache ID is the group ID of the external cache adapter. The application server's dynamic cache sends messages (Invalidates) to the adapter based on the externalcache ID associated with a URI.
Continuing the example scenario previously described, the following is a possible servlet entry in the servletcache.xml file.
<servlet>
<timeout seconds="100"/>
<metadatagenerator class="com.ibm.wte.WteMetaDataGeneratorImpl"/>
<externalcache id="IBM-WTE-XYZ-1"/>
<path uri="/servlet/cTimeStamp"/>
<path uri="/servlet/TimeStamp"/>
</servlet>
All subcomponents of externally accessible servlet results or JSP pages must also be externally cacheable, that is, it must have an externalcache ID defined in the servletcache.xml file.
Java Bean components
The Caching Proxy has two beans in the /opt/IBMWTE/usr/internet/classes/com/ibm/wte directory: WteAdapter.class and WteMetaDataGeneratorImpl.class. Note that for Windows, the directory is C:\Program Files\IBM\WTE\classes\com\ibm\wte. If you have installed the Caching Proxy in a directory other than the default, substitute your installation path. These beans must also be in the application server's CLASSPATH in the application_server_installation/bin/admin.config file. If the application server is not installed on the same machine as the Caching Proxy, then copy these two beans from the Caching Proxy machine to the application server machine.
Invalidation of cache entries
Unlike standard URIs that expire after a predetermined lifespan, JSPs are actively invalidated by the WebSphere Application Server. Content in the proxy's cache is valid until it receives an Invalidate message from the Websphere Application Server.
Entries in the dynamic cache can be invalidated when:
Any invalidation of dynamic cache entries generates an Invalidate message for the specific instance of the Caching Proxy adapter. The Caching Proxy receives Invalidates as posts to the URI /WES_External_Adapter. The Caching Proxy then clears the invalid entries from its cache.
Overview
The LDAP authorization plug-in enables the Caching Proxy to authorize clients by using an LDAP server and user-defined policy information. It does so by directing the authorization routine within the proxy server to retrieve data from an LDAP server rather than from the Caching Proxy registry.
Note that the logical sequence of the authentication/authorization thread calls the authentication routine first, then authorization routine. A single response from either routine indicating a failed login denies access to the proxy server. For example, if a user name exists within both the Caching Proxy registry and the LDAP database with different passwords in each system, and the client attempts to log in using the password stored by the LDAP database, the login attempt fails because the authentication routine reads the Caching Proxy registry, notices an incorrect password, and responds with a failed authentication attempt.
Regardless of whether the proxy server retrieves data from an LDAP server or the Caching Proxy registry, the client's Internet browser creates a consistent pop-up window that prompts the user for a user name and password. Access through the proxy server can be further refined by using a security policy, which allows system administrators to grant or deny access according to defined IP addresses, host names, or group or organizational units within an LDAP database.
A series of shared libraries and a daemon comprise the LDAP authorization plug-in. A ServerInit directive within the ibmproxy.conf file instructs the shared library to initialize the LDAP plug-in daemon when the proxy server starts up. During this initialization, the daemon reads the pac.conf file for configuration directives and policy information. Then, an Authorization directive within the ibmproxy.conf file instructs the proxy server to call the shared library whenever authentication is required. Because the LDAP authorization plug-in handles only authentication and is not involved in the retrieval of requested resources, such as HTML pages, it does not act as a preexit, as do many plug-in modules.
Lightweight Directory Access Protocol (LDAP)
LDAP provides interactive access to X.500 directories with a minimal consumption of system resources. The IANA has assigned TCP port 389 and UPD port 389 to LDAP. For more information, refer to RFC 1777, which defines LDAP.
Installation
The LDAP authorization plug-in is automatically installed during either a PTF upgrade or a new installation of the product. On AIX and Solaris systems, a Caching Proxy library (./lib/), LDAP plug-in library (./lib/plugins/pac/), binary (./bin/), and configuration (./etc/) directories are created within the /opt/IBMWTE/usr/internet/ directory. Symbolic links are then created from the /usr/lib/, /usr/sbin/, and /etc directories to these product specific ones. On Linux systems, though, the product specific directories are not created. All files are installed directly into the common /usr/lib/, /usr/sbin/, and /etc directories.
Four Netscape Directory libraries are also required to use the LDAP plug-in. Netscape Directory SDK for C 4.11 can be downloaded from Netscape's Web site. For AIX and Solaris systems install these libraries into the /opt/IBMWTE/usr/internet/lib/plugins/pac/ directory and create symbolic links to the files from the /usr/lib/ directory. For Linux systems install the libraries directly into the /usr/lib/ directory. For Windows systems, the Netscape Directory SDK installation program installs the product into the appropriate directories and adjusts the paths as necessary.
Directory structure
| UNIX directory | Windows directory | Content |
|---|---|---|
| /opt/IBMWTE/ | \Program Files\IBM\WTE\ | IBM Caching Proxy base directory |
| /opt/IBMWTE/usr/ internet/sbin/ | \Program Files\IBM\WTE\ Bin | IBM Caching Proxy binaries and scripts, except for Linux |
| /usr/sbin/ |
| Symbolic links to /opt/IBMWTE/usr/ internet/sbin. For Linux, actual binaries and scripts are stored here. |
| /opt/IBMWTE/usr/ internet/etc/ | \Program Files\IBM\WTE\ | IBM Caching Proxy configuration files, except Linux |
| /etc/ |
| Symbolic links to /opt/IBMWTE/usr/ internet/etc/. For Linux, actual configuration files are stored here. |
| /opt/IBMWTE/usr/ internet/lib/ | \Program Files\IBM\WTE\ Bin\ plugins\ | IBM Caching Proxy libraries, except for Linux |
| /opt/IBMWTE/usr/ internet/lib/ plugins/pac/ | \Program Files\IBM\WTE\ Bin\plugins\pac\ | LDAP authorization plug-in libraries, except for Linux |
| /usr/lib/ |
| Symbolic links to /opt/ IBMWTE/usr/ internet/lib. For Linux, actual libraries are stored here. |
| /opt/IBMWTE/usr/ internet/server_root/ pac/ | \Program Files\IBM\ WTE\plugins\pac\data\ | LDAP authorization plug-in data storage |
LDAP Plug-in files
| UNIX file name | Windows file name | Description |
|---|---|---|
| libpacwte.so | pacwte.dll | shared library |
| libpacman.so | pacman.dll |
|
| pacd_restart.sh | pacd_restart.bat |
|
| pac.conf | pac.conf | plug-in configuration and policy file |
Netscape Directory SDK libraries
| UNIX file name | Windows file name | Description |
|---|---|---|
| libldapssl41.so | nsldapssl32v41.dll | shared library |
| libplc3.so | libplc3.dll | shared library |
| libplds3.so | libplds3.dll | shared library |
| libnspr3.so | libnspr3.dll | shared library |
Editing the ibmproxy.conf file to enable the LDAP plug-in
Three directives, ServerInit, Authorization, and ServerTerm must be added to the API directives section of the ibmproxy.conf file in order to initialize the LDAP plug-in daemon and redirect the authorization routine. To create these directives, either manually edit the ibmproxy.conf file, or if the proxy server is already running, connect to the Configuration and Administration forms with an Internet browser and open the API Request Processing form (select Server Configuration, Request Processing, and API Request Processing). Each directive must appear on a single line in the proxy configuration file, regardless of whether these examples contain line breaks for clarity.
Note that 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 plug-in 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 plug-in.
The ServerInit directive has three arguments: (1) the fully qualified path of the shared library, (2) the function call, (3) and the fully qualified path of the configuration and policy file. The first and second arguments are delimited by a colon. The second and third arguments are delimited by a space. The first and third arguments are system specific and depend on where the plug-in components are installed. The second argument is hard-coded into the shared library and must be typed exactly as shown. When creating a ServerInit directive using the Configuration and Administration forms, both the second and third arguments must be entered in the Function Name field. The third argument is displayed in the IP Template column.
The Authorization directive has two arguments: (1) the fully qualified path of the shared library and (2) the function call. These arguments are delimited by a colon. The first argument is system specific and depends on where the shared library is installed. The second argument is hard-coded into the shared library and must be typed exactly as shown.
The ServerTerm directive has two arguments: (1) the fully qualified path of the shared library and (2) the function call. These arguments are delimited by a colon. The first argument is system specific and depends on where the shared library is installed. The second argument is hard-coded into the shared library and must be typed exactly as shown. This directive terminates the LDAP authorization daemon when the Caching Proxy shuts down. If the owner of the daemon is different from the owner of the Caching Proxy, the Caching Proxy may be unable to stop the daemon. In which case an administrator must manually stop the daemon.
ServerInit path_of_shared_library:pacwte_auth_init path_of_conf_policy_file
UNIX example:
ServerInit /usr/lib/plugins/pac/libpacwte.so:pacwte_auth_init /etc/pac.conf
Windows example:
ServerInit C:\Program Files\IBM\WTE\Bin\plugins\
pac\pacwte.dll:pacwte_auth_init C:\Program Files\
IBM\WTE\plugins\pac\config\pac.conf
Authorization BASIC path_of_shared_library:pacwte_auth_policy
UNIX example:
Authorization BASIC usr/lib/plugins/pac/libpacwte.so:pacwte_auth_policy
Windows example:
Authorization BASIC C:\Program Files\IBM\WTE\Bin\plugins\
pac\pacwte.dll:pacwte_auth_policy
ServerTerm path_of_shared_library:pacwte_shutdown
UNIX example:
ServerTerm BASIC /opt/IBMWTE/usr/internet/server_root/
plugins/pac/bin/libpacwte.so:pacwte_shutdown
Windows example:
ServerTerm BASIC C:\Program Files\IBM\WTE\plugins\
pac\bin\pacwte.dll:pacwte_shutdown
Editing the pac.conf file
The configuration and policy file, pac.conf, must be manually edited by using a text editor. A directive name is separated from its first argument by a colon. Multiple arguments are delimited by commas. Remarks are included in the configuration and policy file to assist in editing it. Key policy directives are shown below. The policy stanza is specifically addressed within the next section.
[PAC_MAN_SERVER]
hostname: #
port: # port PacD is listening on
default_policy:[grant|deny] # describes the default policy for users
# that are not described in the POLICY section
[PAC_PLUGIN]
hostname_check:[true|false] # enables DNS lookup. Must have
# DNS lookup turned on for ibmproxy to work.
[LDAP_SERVER]
hostname: # LDAP Server hostname
port:389 # Port LDAP is listening on
search_base: # Portion of the LDAP tree to search for policy info
search_key: # ID field tosearch
[CACHE]
cred_cache_enabled [TRUE|FALSE] # turn credentials cache on
cred_cache_min_size:100 # minimum number of credentials to cache in pacd
cred_cache_max_size:64000 # maximum number of credentials to cache in pacd
cred_cache_expiration:86400 # when a credential expires
policy_cache_enabled:{TRUE|FALSE} # turns policy cache on/off
policy_cache_min_size:100 # min. number of policy related items to cache in pacd
policy_cache_max_size:64000 # max. number of policy related items to cache in pacd
policy_cache_expiration:86400 # when a policy related item expires
Writing an LDAP policy
Every LDAP policy uses the following template within the configuration and policy file. Each policy must begin with the uppercase keyword POLICY in brackets.
[POLICY]
id: # the id for the LDAP entry or ip/hostname
# (wildcard supported, such as *.ibm.com
grant:[true|false] # true means to grant access, false means
# to deny access
type:[0|1|2|3] # 0 LDAP entry that is a group,
# 1 LDAP entry that is not a group,
# 2 IP address, 3 hostname
propagate:[true|false] # true means that the access rights (grant
# or deny) will be propogated to all
# descendants or members
stop_entry:[entry|NULL] # Propagation of the access right stops
# at this entry.If the id is a group,
# stop_entry must be set to NULL.
# stop_entry may be applied to an IP
# address or hostname. Each stop_entry
# must be on its own line
exception_entry:[entry|NULL] # Assignment of the access right skips
# these entries, but continues through their subtrees.
# This may be a list of entries.
# exception_entry may be applied to a group,
# IP address, or hostname. Each
# exception_entry must be on its own line.
The wildcard (*) is supported only for the last position of an IP address or the first position of a host name in the id and stop_entry directives. Wildcards are not supported in the exception_entry. Wildcards are not supported for any LDAP entries in any fields.
Multiple policies are supported, and the value false always takes priority if policies conflict. In other words, a single denial in any policy blocks access. The order in which the policies are listed in the configuration and policy file is irrelevant and does not establish a priority.
For a set of policy examples, refer to the pac.conf file in the configuration files directory.
Starting and stopping pacd
The LDAP authorization daemon runs as the pacd process. The /usr/sbin/pacd_restart.sh (UNIX) or \Program Files\IBM\WTE\Bin\pacd_restart.bat (Windows) scripts restart the daemon without interrupting the Caching Proxy.
The ICP plug-in enables a Caching Proxy to query Internet Caching Protocol (ICP) compliant caches in search of HTML pages and other cacheable resources. When the proxy server receives an HTTP request, it searches its own cache for the resource. If the resource is not found in the local cache and the ICP plug-in is enabled, the proxy server wraps the URL within an ICP query packet and then delivers this packet to all identified ICP peer caches. If a peer cache responds with a hit, indicating that it has the sought-after resource, the original server retrieves the resource from the appropriate peer's cache. If two or more peers respond with hits, the first response is processed. If no peers respond with hits, the original server continues to process the request according to its workflow. For example, it can invoke another preexit, continue to the Remote Caching Access (RCA) routine, if enabled, or it can simply retrieve the requested URL itself.
Configuration
The ICP plug-in is configured by editing the proxy configuration file, ibmproxy.conf. A ServerInit directive, a PreExit directive, or both must be added to the API directives section of the ibmproxy.conf file in order to initialize the ICP plug-in. For the Caching Proxy to function as an ICP server, initialize the ICP plug-in by using the ServerInit directive; for it to function as an ICP client, initialize the ICP plug-in by using the PreExit directive. To create these directive, either manually edit the ibmproxy.conf file, or, if the proxy server is already running, connect to the Configuration and Administration forms with an Internet browser and open the API Request Processing form (select Server Configuration, Request Processing, and API Request Processing). Each directive must appear on a single line in the proxy configuration file, regardless of whether these examples contain line breaks for clarity.
Note that 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 plug-in 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 plug-in.
Both the ServerInit and the PreExit directives have two arguments: (1) the fully qualified path of the shared library and (2) the function call. These arguments are delimited by a colon. The first argument is system specific and depends on where the plug-in components are installed. The second argument is hard-coded into the shared library and must be typed exactly as shown.
ServerInit path_of_shared_library:icpServer
UNIX example:
ServerInit /opt/IBMWTE/usr/internet/lib/plugins/icp/
libicp_plugin.so:icpServer
Windows example:
ServerInit C:\Program Files\IBM\WTE\Bin\plugins\
icp\icpplugin.dll:icpServer
PreExit path_of_shared_library:icpClient
UNIX example:
PreExit /opt/IBMWTE/usr/internet/lib/plugins/icp/
libicp_plugin.so:icpClient
Windows example:
PreExit C:\Program Files\IBM\WTE\Bin\plugins\
icp\icpplugin.dll:icpClient
Depending upon your method of installing the Caching Proxy v3.6, you either need to edit or add the following directives to your ibmproxy.conf file. See WTE Directives for details.
<MODULEBEGIN> ICP ICP_Address ICP_Port ICP_Timeout, ICP_Peer ICP_MaxThreads ICP_PingInterval <MODULEEND>
The CyberPatrol filtering plug-in allows Web content filtering based on the SurfControl database of acceptable and unacceptable Web sites. Note that because the CyberPatrol software product was acquired by the SurfControl company shortly before this release, the name "SurfControl" is used to describe the database and support services that the company provides, and the name "CyberPatrol" describes the filtering software used in the plug-in.
SurfControl maintains a database of Web sites whose content can be subject to filtering. The database is assembled by SurfControl staff, who judge whether a Web site is included in any of their filtering categories. Two filtering methods are available. Choosing the CyberNOT method blocks access to Web sites that are listed in the negative categories, and choosing the CyberYES method allows access only to Web sites included in the positive categories. In addition to the database-based filtering, the plug-in allows you to specify additional Web sites to block or to allow.
Possible categories to select, and their hexidecimal configuration codes, follow. Details about the types of material included in each category are available from the SurfControl Web site, http://www.surfcontrol.com.
CyberNOT categories:
Violence/Profanity - 0x0001
Partial Nudity - 0x0002
Full Nudity - 0x0004
Sexual Acts - 0x0008
Gross Depictions - 0x0010
Intolerance - 0x0020
Satanic/Cult - 0x0040
Drugs/Drug Culture - 0x0080
Militant/Extremist - 0x0100
Sex Education - 0x0200
Questionable/Illegal & Gambling - 0x0400
Alcohol & Tobacco - 0x0800
Sports & Entertainment - 0x1000
Search Engines - 0x8000
CyberYES categories:
Games & Toys - 0x0001
Art, Books & Music - 0x0002
Movies & TV - 0x0004
Outdoors & Sports - 0x0008
Oceans & Space - 0x0010
Pets, Animals & Dinosaurs - 0x0020
Other Interesting Stuff - 0x0040
Vacations & Travel - 0x0080
Puzzles & Hobbies - 0x0100
School Work - 0x0200
Volunteer & Help - 0x0400
Kids - 0x0800
Teens - 0x1000
Reference Materials - 0x2000
Schools on the Net - 0x4000
Parents & Teachers - 0x8000
Installation and configuration
The SurfControl database is delivered in the Caching Proxy product and installed automatically. You must update the database files periodically to maintain a current list of Web sites that SurfControl has ranked. One year of free database updates is included with the Caching Proxy software; after the first year, customers must contract with SurfControl to receive new updates. Database updates include a domain name server (DNS) file that expedites access to sites in the SurfControl database by providing IP address lookup.
Note that the SurfControl database requires approximately 30MB of storage space. If adequate space is not available, content filtering based on the SurfControl database can possibly fail.
The CyberPatrol filtering feature in the Caching Proxy is enabled and configured by editing the proxy configuration file, ibmproxy.conf, or by using the Configuration and Administration forms. The CyberPatrol configuration form is listed in the Plug-ins category.
Configuring the CyberPatrol plug-in involves five basic steps.
Add the ServerInit directive and PreExit directive to the Caching Proxy configuration file, ibmproxy.conf, to direct the proxy to consult the plug-in when it starts up and when it begins to process a request. To create these directive, either manually edit the ibmproxy.conf file, or, if the proxy server is already running, connect to the Configuration and Administration forms with an Internet browser and open the API Request Processing form (select Server Configuration, Request Processing, and API Request Processing). Each directive must appear on a single line in the proxy configuration file, regardless of whether these examples contain line breaks for clarity.
Note that 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 plug-in 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 plug-in.
ServerInit /opt/IBMWTE/usr/internet/lib/plugins/cyberpatrol/ libcpfilter.o:cpfilterInit PreExit /opt/IBMWTE/usr/internet/lib/plugins/cyberpatrol/ libcpfilter.o:cpfilterMain
ServerInit /opt/IBMWTE/usr/internet/lib/plugins/cyberpatrol/ libcpfilter.so:cpfilterInit PreExit /opt/IBMWTE/usr/internet/lib/plugins/cyberpatrol/ libcpfilter.so:cpfilterMain
ServerInit /opt/IBMWTE/usr/internet/server_root/filter/cyberpatrol/ libcpfilter.so:cpfilterInit PreExit /opt/IBMWTE/usr/internet/server_root/filter/cyberpatrol/ libcpfilter.so:cpfilterMain
ServerInit C:\Program Files\ibm\wte\bin\plugins\filter\cyberpatrol\ cpfilter.dll:cpfilterInit PreExit C:\Program Files\ibm\wte\bin\plugins\filter\cyberpatrol\ cpfilter.dll:cpfilterMain
If you have installed the Caching Proxy software in a directory other than the default, substitute your installation path.
To specify a filtering method, use the radio buttons in the configuration form or the FilterCyberPatrolList directive in the ibmproxy.conf file.
To specify categories to filter, use the check boxes on the form or set the FilterCyberPatrolRuleMask directive. When using the FilterCyberPatrolRuleMask directive to specify categories to filter, you must construct the rule mask, which is a hexidecimal code that describes all categories you want to filter, by adding the codes for each individual category. Each code starts with 0x and then includes four digits in hexidecimal format. Adding the digits in each position yields the rule mask. For example, in CyberNOT, to filter on the categories related to sex, add the codes 0x0002 (Partial Nudity) + 0x0004 (Full Nudity) + 0x0008 (Sexual Acts) + 0x0200 (Sex Education) for a rule mask of 0x020e. For additional directive information, see WTE Directives.
To specify additional URLs or keywords to filter, use the list on the configuration form or use the FilterAdditionalURL directive. To specify URLs to exclude from filtering, use the list on the configuration form or use the FilterExceptionURL directive. For directive information, see WTE Directives.
You also can specify additions in a separate file. To set up exception or additional URLs in their own files rather than listing them in the ibmproxy.conf configuration file, do the following:
www.xxmag.com adult nudepic xxx
On UNIX and Linux systems, these variables can be set by issuing the following commands:
setenv FILTER_URL_PATTERN_FILE /opt/IBMWTE/usr/internet/
server_root/filter/cyberpatrol/additions_filename
setenv FILTER_URL_EXCEPTION_FILE /opt/IBMWTE/usr/internet/
server_root/filter/cyberpatrol/exceptions_filename
On Windows systems, access environment variable settings by selecting System from your Windows Control Panel.
Alternatively, for UNIX and Linux systems, add the following lines to the CyberPatrol plug-in initialization file, which is server_root/filter/cyberpatrol/setup_state. Settings in this file override any system environment settings. These settings must not contain line breaks.
FILTER_URL_PATTERN_FILE=/opt/IBMWTE/usr/internet/ server_root/filter/cyberpatrol/additions_filename FILTER_URL_EXCEPTION_FILE=/opt/IBMWTE/usr/internet/ server_root/filter/cyberpatrol/exceptions_filename
For Windows systems, the path is installation_path\bin\plugins\filter\cyberpatrol, where the installation path is generally C:\Program Files\IBM\WTE.
To update the filter database by using the configuration forms, first submit the information on the form, then click Update Filter Files. To update the filter database by using a command-line interface, first save changes to the proxy configuration file, then issue the GenCyberDB command from the installation_path/filter/cyberpatrol directory for UNIX platforms, or the installation_path\bin\plugins\filter\cyberpatrol directory for Windows platforms. (For UNIX platforms, the installation path is usually /opt/IBMWTE/usr/internet/server_root/. For Windows platforms, the installation path is usually C:\Program Files\IBM\WTE\. If you installed your software in a different path, use that path.)
The plug-in's additional filtering methods, which are based on keywords or patterns and on URLs, do not rely on the database, and these methods are effective on non-English Web sites.
Minimum browser requirements
To configure the Caching Proxy v3.6 by using the Configuration and Administration forms, your browser must do the following:
Recommended browsers
The following browsers have been tested with the Caching Proxy v3.6 Configuration and Administration forms.
| Microsoft Windows NT 4/2000 | English | Netscape v4.72, v4.76
Microsoft IE v5.0, v5.5 |
| Other languages | Netscape v4.51
Microsoft IE v5.0, v5.5 | |
| AIX | All | Netscape v4.7 |
| Solaris | English | Netscape v4.75 |
| Linux | All | Netscape v4.72 |
In order to properly display forms, the operating system that is actually displaying the form (the one on which the browser resides) must contain the appropriate font sets for the language in which the form is written. The browser interface, however, does not necessarily need to be in the same language as the forms. For example, a Chinese version of the proxy server is running on a Solaris 7 system. A Netscape browser with an English-language interface is loaded onto the Solaris host because a Chinese version is not available. This browser can be used to locally edit the Configuration and Administration forms. Or, if a Windows workstation with Chinese language support is available to remotely connect to the proxy server, it is possible to load a Chinese version of a Netscape browser onto the Windows workstation and use this browser to edit the forms. This second solution has the advantage of maintaining a consistent language interface for the administrator.
The operating system specific font sets greatly affect the display of various languages, particularly of double-byte characters, within the browsers. For example, a Chinese font set on AIX does not look exactly the same as a Chinese font set on Windows platforms. This causes some irregularities in the appearance of HTML text and Java applets within the Configuration and Administration forms. For the best appearance, only browsers running on Windows operating systems are recommended.
Notes about Netscape 4.x browsers
Netscape browsers have limitations associated with displaying the Caching Proxy Configuration and Administration forms that include, but are not necessarily limited to, the following:
Netscape 6 not supported
Netscape 6 is not supported for use with the Caching Proxy Configuration and Administration forms.
This section discusses issues pertaining to the ibmproxy.conf file. With the exception of the first note, this section applies only to AIX, Solaris, and Linux platforms.
ibmproxy.conf no longer translated
This note applies to all platforms. With the v3.6 release of the Caching Proxy, remarks in the proxy server's configuration file are no longer translated. Appendix A of the IBM Web Traffic Express User's Guide, version 1.0, provides translated information about the original version 1.0 directives. This README provides coverage of directives required by new caching proxy features.
ibmproxy.conf is not replaced during a PTF upgrade
A PTF upgrade refers to installing an updated version of the proxy server from a PTF (Program Temporary Fix) image, which is distributed only to existing customers. Installing this PTF image requires that an existing IBM Caching Proxy already exists on the target system.
During a PTF upgrade on AIX, Solaris, and Linux systems, original proxy server configuration files are restored after the updated packages are installed. While this procedure maintains all existing proxy server settings, it does not automatically add the directives required to support new features. To enable new features, the additional directives must be manually added to the ibmproxy.conf file. Using a PTF upgrade has the advantage of not replacing a translated ibmproxy.conf with an English version.
An English-only, updated ibmproxy.conf file (ibmproxy.conf.new) is installed during a PTF upgrade. The new configuration file is installed in the same directory as the existing ibmproxy.conf file. On AIX and Solaris, this is /opt/IBMWTE/usr/internet/etc. On Linux, this is /etc.
ibmproxy.conf is possibly replaced during a full installation
A full installation refers to installing the proxy server software from either a CD or a complete product image. The full installation does not require a preexisting installation of the Caching Proxy, although it can be used to update a previous installation.
During a full installation on AIX, Solaris, and Linux systems, any existing proxy server configuration files, including language-specific ibmproxy.conf files, are copied to /opt/IBMWTE/usr/internet/server_root/oldfiles. (On a new installation, no old proxy server configuration files exist to be backed up.) The new configuration file is in English only and contains proxy server settings defined during the installation routine. The old configuration files may be referred to when manually modifying the current configuration file, or if the translated remarks are needed.
Note: Second and subsequent installs or upgrades replace these backup files with the latest configuration files in the /etc and /etc/ibmproxy directories.
Where is the real ibmproxy.conf file?
When the Caching Proxy starts, regardless of the method used to initiate it, the proxy server program reads the LC_ALL and LANG environment variables. These variables tell the proxy server in which language the operating system is communicating. For all languages except English and unless flagged to look elsewhere, the proxy server reads the ibmproxy.conf located in the /etc/ibmproxy/language specific directory. For English, or if a language specific configuration file does not exist, the proxy server uses a default path of /etc/ibmproxy.conf. For AIX and Solaris operating systems, the ibmproxy.conf files within the /etc and /etc/ibmproxy/language specific directories are created as symbolic links to the actual files stored in the /opt/IBMWTE/usr/internet/etc and /opt/IBMWTE/usr/internet/etc/language specific directories. For Linux operating systems, the ibmproxy.conf files within the /etc and /etc/ibmproxy/language specific directories are the actual files.
It is possible to install several language versions of the Caching Proxy on one server. Additional /etc/ibmproxy/language specific directories are created. Also, additional language specific directories are created within the /opt/IBMWTE/ directory. Even though WTE 3.6 ibmproxy.conf files do not have translated remarks, the individual ibmproxy.conf files have all had paths corrected to point to the appropriate language specific directories. They are not all identical.
To avoid issues in determining the language in which to start the proxy server, the LC_ALL and LANG environment variable must both be set to the same values.
The proxy server program may be flagged during startup to read a particular configuration file. Example: ibmproxy -r /usr/etc/ibmproxy.conf. Refer to the IBM Web Traffic Express User's Guide for more information on starting the proxy server.
A locale is a collection of environment variables that instructs the operating system on how to interface with a user. These variables define the language in which system messages are displayed, how time and numbers are expressed, even which monetary units are used. The actual locales are typically stored in /usr/lib/locale. Refer to your system documentation for more information. The two primary locale variables are LANG and LC_ALL. The LANG variable sets the interface language. The LC_ALL variable sets most other interface displays. On some systems, a series of LC_child variables may exist to enable setting specific interfaces, such as the monetary unit (LC_MONETARY). On these systems, the LC_ALL variable is the parent whose value is inherited unless the child value is specifically set.
Here are some locale-related commands:
export LANG=de_DE export LC_ALL=de_DE
setenv LANG=de setenv LC_ALL=de
Supported locales
| Language | AIX Locale | Solaris Locale | Linux Locale |
|---|---|---|---|
| Brazilian | pt_BR | pt_BR | not supported |
| Chinese (Simplified) | zh_CN; zh_CN.IBM-euc.CN | zh_CN; zh | not supported |
| Chinese (Traditional) | Zh_TW; zh_TW; Zh_TW.big5; zh_TW.IBM-eucTW | zh_TW; zh_TW.BIG5 | not supported |
| English | en_US | en_US | en_US |
| French | fr_FR | fr_FR fr | fr_FR |
| German | de_DE | de_DE de | de_DE |
| Italian | it_IT | it_IT it | not supported |
| Japanese | ja_JP; ja_JP.PCK; Ja_JP | ja_JP; ja; ja_JP.PCK | ja_JP |
| Korean | ko_KR; ko_KR.IBM-eucKR | ko_KR; ko | not supported |
| Spanish | es_ES | es_ES; es | not supported |
Items can now be cached based only on a specified (significant) part of the incoming URL, instead of the full URL. This is useful in transaction-model Web serving because the same response is often returned for varying incoming requests when significant parts of the incoming requests' URIs are identical.
Use the SignificantUrlTerminator directive to specify a terminating code for URL requests. Using the terminating code in a request causes the 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, the Caching Proxy compares incoming URLs against the terminator codes in the order in which they are defined in the ibmproxy.conf file. See WTE Directives for more information.
The RTSP Redirector provides streaming media redirection support in the Caching Proxy. This enables the proxy to act as a first point of contact with media players and to redirect their requests to an appropriate proxy server or to a content server that then provides the requested media content. Previously, the RTSP Redirector was subject to the limitation that all requests to the same origin server for any URL were redirected the same way; redirection based on file names or other portions of the requested URL was not possible.
This limitation no longer applies. The RTSP Redirector now uses the complete URL from received requests along with the threshold value (rtsp_proxy_threshold) set in the Caching Proxy configuration file to determine whether to redirect the client request to the origin server or a proxy server. Requests to the same origin server are now handled on a case-by-case basis as redirection is now based on the full URL.
When the Caching Proxy is used as a reverse proxy server, requests between clients and the Caching Proxy, or requests between content servers and the Caching Proxy, or both, can be made secure by using Secure Sockets Layer (SSL). Previously, SSL support was subject to the limitation that it was not possible to have a single Caching Proxy machine acting as a reverse proxy for multiple domains that offered individual SSL certificates. This limitation no longer applies. The Caching Proxy, acting as a reverse proxy for multiple domains, can now determine the correct certificate to hand out based on the domain to which the request is sent. This new feature is configured by using the SSLCertificate directive in the ibmproxy.conf file. See WTE Directives for details.
Only a 128-bit encryption version of the Caching Proxy is being delivered. The 56-bit version is no longer available. If you are updating a previous version, you can install the Caching Proxy directly to your currently installed 128-bit or 56-bit version. If you were previously using a 56-bit (export) browser, you must upgrade to a 128-bit browser in order to take advantage of the 128-bit encryption in the proxy.
After an upgrade from a 56-bit version of the Caching Proxy to the 128-bit version, if the key size used to encrypt certificates is set to 1024, then no configuration change is necessary. However, if the key size is set to 512, in order to take advantage of the proxy's 128-bit encryption, you must create new certificates with a key size of 1024. Create new keys by using the IBM Key Manager utility (IKEYMAN).
See the IBM Web Traffic Express User's Guide for a detailed discussion of the IBM Key Manager utility.
Note that, as with the General Availability product, this version of the product does not support encryption on SuSE Linux.
If a message appears in the Caching Proxy error log about the security library not being loaded (with a return code of 126), the cause can possibly be one of the following two errors.
On Linux systems, the cbrcontrol utility sometimes does not start after installation. The Caching Proxy standard error log /opt/IBMWTE/usr/internet/server_root/logs/ibmproxy-stderr.date shows a message like the following:
Error finding class for CMN_NLS.
This problem occurs because permissions are not set correctly on the /opt/nd directory. To correct this problem, issue the following command and restart the Caching Proxy.
chmod ugo+rx /opt/nd
If the Caching Proxy service (Web Traffic Express) appears to be started in the Services panel but the proxy is not working, the machine might not have been restarted after the proxy was installed. The machine must be restarted so that the value of the PATH environment variable is refreshed in the Windows registry. If the registry is not refreshed, it is possible for the PATH variable to show the correct WTE and GSK4 paths but function incorrectly.
If the Caching Proxy service is set to interact with the desktop, and a pop-up box with the error message Message catalog error: the message catalog could not be loaded or is invalid appears when the service is started, the machine might not have been restarted after the Caching Proxy was installed. The machine must be restarted so that the value of the PATH environment variable is refreshed in the Windows registry. If the registry is not refreshed, it is possible for the PATH variable to show the correct WTE and GSK4 paths but function incorrectly.
Asynchronous I/O must be set to available in order to successfully install the Caching Proxy software on an AIX machine.
Several methods exist for changing this setting. The following are two examples.
chdev -l aio0 -a autoconfig=available
You must have superuser root authority on the local machine to configure asynchronous I/O. Note that changes to this setting are not effective until the system is restarted.
Additional information about setting asynchronous I/O is available in Chapter 17 of the WebSphere Edge Server Getting Started, under the heading "Installation prerequisites for AIX systems."
The Caching Proxy does not function correctly without the full host name, including the domain name, of the machine on which it is installed. Ensure that the Hostname directive in the Caching Proxy configuration file, ibmproxy.conf, specifies the fully qualified host name, including the domain. Alternatively, before running the Setup program, supply a default domain name and restart the machine. To supply a default domain name for your computer, right-click the My Computer icon, select Properties, select the Network Identification tab, click Properties, click More, and enter the domain suffix in the field provided.
Solaris file descriptor limit
It is possible that the Caching Proxy system startup script can fail to set the desired maximum number of file descriptors due to the Solaris systemwide limit on file descriptors. If the systemwide maximum is less than the setting in the Caching Proxy system startup script, then the systemwide limit is used.
To avoid proxy performance problems that can possibly result from having a system hard limit for file descriptors set too low (less than 1024), you can change the file descriptor limit. Issue the ulimit command to view the number of descriptors that are currently available. If the value is less than 1024, increase the file descriptor limit.
To increase the file descriptor limit to 1024, add the following line to the /etc/system file:
set rlim_fd_cur=0x400
TCP/IP configuration
The following TCP/IP configuration is recommended for best performance of Web servers. You can make this configuration persistent by modifying the /etc/init.d/inetinit file to contain the following commands:
/usr/sbin/ndd -set /dev/tcp tcp_rexmit_interval_max 10000 /usr/sbin/ndd -set /dev/tcp tcp_ip_abort_interval 6000 /usr/sbin/ndd -set /dev/tcp tcp_time_wait_interval 6000 /usr/sbin/ndd -set /dev/tcp tcp_keepalive_interval 6000
Installation of the Caching Proxy software requires installation of the GSKit software, which is mainly used for SSL support. Although the GSKit software is not supported for SuSE Linux, it must be installed in order for the Caching Proxy to function.
If you use the Linux package installer to install the Caching Proxy software on a SuSE Linux system, you must specify the nodeps option when installing the basic GSKit package. This option causes the package installer to ignore certain software dependencies that are not consistent with SuSE Linux. The syntax follows.
rpm -ivh gsk4bas-4.0-3.43.i386.rpm --nodeps
Note that two -es are used with the nodeps flag.
This step is completed automatically if you use the installation script to install the Caching Proxy software on a SuSE Linux machine. Additional information about using the installation script or the Linux package installer to install Caching Proxy software is available in the Web Traffic Express User's Guide.
The IBM WebSphere Edge Server for Multiplatforms Getting Started contains product notes, some of which describe limitations associated with the Caching Proxy. Some of the problems described may have been corrected. For a complete list of fixes, refer to the following IBM Web site:
http://www.ibm.com/software/webservers/edgeserver/efix-wte.html
The following documentation corrections apply to the IBM WTE Programming Guide:
The following documentation corrections apply to the IBM WTE User's Guide:
NoBG [on | off]
The following documentation corrections apply to the Configuration and Adminstration forms:
These notes apply to the load-balancing component of WebSphere Edge Server.
Non-English-language versions of the Load Balancer are not available on Solaris and Linux platforms. For Solaris and Linux, the Load Balancer is available in English.
Access information about Load Balancer subcomponents in the README files located in the Load Balancer product installation directory. These READMEs contain corrections that apply to the IBM Network Dispatcher User's Guide.
The IBM WebSphere Edge Server for Multiplatforms Getting Started contains product notes, some of which describe limitations associated with the Load Balancer. Some of the problems described may have been corrected. For a complete list of fixes, refer to the following IBM Web site:
http://www.ibm.com/software/webservers/edgeserver/efix-nd.html
The Load Balancer requires Java 1.3 on all supported platforms: AIX, Red Hat Linux, Solaris, Windows NT, and Windows 2000. Java 1.1.x is no longer supported.
The following are the Java 1.3 requirements by platform:
AIX:
AIX 4.3.3.10 plus APARs is required to support Java 1.3. Refer to the README for the IBM AIX Developer Kit for a list of required AIX APARs.
IBM AIX Developer Kit, Java 2 Technology Edition, Version 1.3.0 for the Java Runtime Environment
Red Hat Linux:
IBM Runtime Environment for Linux, Java 2 Technology Edition, Version 1.3.0
Assign to your JAVA_HOME environment variable the directory where Java is installed, for example: /opt/IBMJava2-13/jre
Add to your PATH environment variable: $JAVA_HOME/bin:$PATH
Solaris:
Java 2 JRE, Standard Edition, Version 1.3.0
Add to your PATH environment variable: /usr/j2se/bin
Windows NT and Windows 2000:
IBM Cross Platform Technologies for Windows v2.0 (SDK 1.3) Note that you must download both the Developer Kit installable package and the Runtime Environment installable package prior to running the InstallShield program.
For ISS component only, if the Load Balancer is unable to find where Jave 1.3 is installed from the Registry, then define an environment variable IBMND_JRE_LOCATION which should be set to the fully qualified path for the jvm.dll file. For example:
IBMND_JRE_LOCATION="c:\Progra~1\IBM\Java13\jre\bin\classic\jvm.dll"
To configure the Caching Proxy for Java 1.3 (when using CBR with HTTP or SSL), the following updates are required by platform. (For general information on configuring the Caching Proxy for CBR, refer to Chapter 7 of the IBM Network Dispatcher User's Guide version 3.0 for Multiplatforms.)
AIX:
Add to your LIBPATH environment variable: /usr/java130/jre/bin:/usr/java130/jre/bin/classic
Red Hat Linux:
Assign to your JAVA_HOME environment variable the directory where Java is installed, for example: /opt/IBMJava2-13/jre
Add to your PATH environment variable: $JAVA_HOME/bin:$PATH
Add to your LD_LIBRARY_PATH environment variable: /opt/IBMJava2-13/jre/bin;/opt/IBMJava2-13/jre/bin/classic
Add to your CBR configuration file (ibmproxy.conf): /opt/IBMJava2-13/jre/bin/classic
Solaris:
Add to your LD_LIBRARY_PATH environment variable: /usr/j2se/jre/lib/sparc
Windows NT and Windows 2000:
Add to your PATH environment variable: c:\Progra~1\IBM\Java13\jre\bin;c:\Progra~1\IBM\Java13\jre\bin\classic
Compile command for custom advisors using Java 1.3
Custom advisors are written in Java language. These files are referenced during compilation:
Your classpath must point to both the custom advisor file and the base classes file during the compilation. For Windows, the following is an example compile command:
javac -classpath install_dir\nd\dispatcher\lib\ibmnd.jar ADV_fred.java
where:
The output for the compilation is a class file, such as ADV_fred.class. Before starting the advisor, copy the class file to the dispatcher\lib or cbr\lib directory where the Load Balancer is installed.
The Load Balancer now supports 1 Gb (gigabit) Ethernet NICs (Network Interface Cards) on all supported platforms: AIX, Red Hat Linux, Solaris, Windows NT, and Windows 2000.
The Load Balancer now supports quad-port Ethernet NICs on all platforms: AIX, Red Hat Linux, Solaris, Windows NT, and Windows 2000. For Solaris only, you must edit the /opt/nd/dispatcher/ibmnd.conf file. In the ibmnd.conf file, substitute qfe -1 0 ibmnd (Quad-port Ethernet) to replace hme -1 0 ibmnd (default for 100 Mb Ethernet).
The link-level fault tolerance feature of quad-port NICs is not supported.
The trunking feature of quad-port NICs is not supported.
In addition to supporting Solaris Version 2.6 and Solaris Version 7 (32-bit mode), the Load Balancer now also supports Solaris Version 8 (32-bit mode). For Solaris 8, there is a new ifconfig command to add an alias to the loopback device:
ifconfig lo0:1 plumb <cluster_address> netmask netmask up
To remove an alias from the loopback device:
ifconfig lo0:1 unplumb
For Solaris hardware requirements, refer to Chapter 2 of the "IBM Network Dispatcher User's Guide Version 3.0 for Multiplatforms.
In addition to supporting Red Hat Linux version 6.1 (Linux kernel version 2.2.12-20, as well as any additional fixes to 2.2.12), the Load Balancer now also supports Red Hat Linux version 6.2 (Linux kernel version 2.2.16-3, as well as any additional fixes to 2.2.16).
For Red Hat Linux 6.2, when configuring a collocated server, you must issue the following echo commands:
echo 1 > /proc/sys/net/ipv4/conf/lo/hidden echo 1 > /proc/sys/net/ipv4/conf/all/hidden
Note that Red Hat Linux 6.2 (Linux kernel version 2.2.16-3) does NOT require a patch to support both collocation and high availability at the same time.
For Red Hat Linux requirements, refer to Chapter 2 of the IBM Network Dispatcher User's Guide Version 3.0 for Multiplatforms.
Collocated server support for Red Hat Linux v6.1 is available for the Dispatcher component. Collocation refers to installing the Load Balancer on a server machine that it is also load balancing. With this release, the Load Balancer now fully supports collocation and high availability at the same time for Red Hat Linux 6.1 (Linux kernel version 2.2.12-20).
In earlier releases, the Load Balancer supported collocation for Red Hat Linux but did not support both collocation and a high availability configuration at the same time. In order to configure both collocation and high availability at the same time, you must install a Linux kernel patch.
For information about installing the patch, see IBM Network Dispatcher User's Guide Version 3.0, Chapter 8, section "Installing the Linux kernel patch (for aliasing the loopback adapter)." However, when following these instructions, omit steps 9 and 10 because you do not want to alias the loopback adapter. Add the ifconfig instruction to alias the loopback adapter in the goStandby high-availability script file that is executed when a Dispatcher goes into standby state.
Note that Red Hat Linux v6.2 (Linux kernel version 2.2.16-3) does NOT require a patch in order to support both collocation and high availability at the same time.
Capacity utilization and bandwidth rules are available for the Dispatcher component. Using the capacity utilization feature, Dispatcher measures the amount of data delivered by each of its servers. Dispatcher tracks capacity at the server, rule, port, cluster, and executor levels. For each of these levels, there is a new byte counter value: kilobytes transferred per second. The rate value (kilobytes transferred per second) is calculated over a 60 second interval. You can view these capacity values from the GUI or from the output of a command-line report.
Dispatcher allows you to allocate a specified bandwidth to sets of servers within your configuration using the "reserved bandwidth" rule. When traffic exceeds the reserved bandwidth threshold, you can do either of the following:
By using the shared bandwidth rule in conjunction with the reserved bandwidth rule, as described above, you can provide preferred clients with increased server access and optimal performance for their transactions. For example, using the shared bandwidth rule to recruit unused bandwidth, you can allow online trading customers executing trades on server clusters to receive greater access than customers using other server clusters for investment research.
Note the following to determine whether bandwidth rules can help you manage the volume of response traffic that flows from servers to clients:
Configuring the two new rules associated with capacity utilization (the reserved bandwidth rule and the shared bandwidth rule):
Reserved bandwidth rule
The reserved bandwidth rule allows you to balance loads based on the number of kilobytes per second being delivered by a set of servers. By setting a threshold (allocating a specified bandwidth range) for each set of servers throughout the configuration, you can control and guarantee the amount of bandwidth being used by each cluster-port combination. An example of the new rule type, "reservedbandwidth", for the ndcontrol rule command follows:
ndcontrol rule [add] cluster:port:rule type reservedbandwidth beginrange low endrange high
(The low beginrange is an integer that defaults to 0, and the high endrange is an integer value that defaults to 2 to the 32nd power minus 1.)
Shared bandwidth rule
If the amount of data transferred exceeds the limit for the reserved bandwidth rule, the shared bandwidth rule provides the ability to recruit unused bandwidth available at the site. You can configure this rule to share bandwidth at either the cluster or the executor level. Sharing bandwidth at the cluster level allows a port (or ports) to share a maximum amount of bandwidth across several ports (applications/protocols) within the same cluster. Sharing bandwidth at the executor level allows a cluster (or clusters) within the entire Dispatcher configuration to share a maximum amount of bandwidth. Prior to configuring the shared bandwidth rule, you must specify the maximum amount of bandwidth (kilobytes per second) that can be shared at the executor or cluster level using ndcontrol executor or ndcontrol cluster command with the sharedbandwidth option. The following are examples of the command syntax:
ndcontrol executor [set] sharedbandwidth value ndcontrol cluster [add | set] cluster sharedbandwidth value
(The value for the sharedbandwidth option is an integer value. The default is 0. If the value is 0, then bandwidth cannot be shared.)
ndcontrol rule [add] cluster:port>:rule type sharedbandwidth sharelevel value ndcontrol rule [set] cluster:port:rule sharelevel value
(The value for sharelevel is either executor or cluster. Sharelevel is a required parameter on the sharebandwidth rule.)
The server evaluation option is available for the Dispatcher component. In addition to the bandwidth rules, there is a new rule option "evaluate" on the ndcontrol rule command. Use the "evaluate" keyword to choose to evaluate the rule's condition across all the servers within the port or to evaluate the rule's condition across just the servers within the rule. Note that in earlier versions of the Load Balancer, you were able to measure only each rule's condition across all servers within the port.
The option to measure the rule's condition across the servers within the rule allows you to configure two rules with the following characteristics: The first rule that is evaluated contains all the servers maintaining the content, and the evaluate option is set to "rule" (specifying that the rule's condition is evaluated).
The second rule is an "always true" rule that contains a single server that responds with a "site busy" type response. The result is that when traffic exceeds the threshold of the servers within the first rule, traffic is sent to the "site busy" server within the second rule. When traffic falls below the threshold of the servers within the first rule, new traffic continues once again to the servers in the first rule. On the other hand, if you set the evaluate option to "port" for the first rule (specifying that a rule's condition is evaluated across all servers within the port), when traffic exceeds the threshold of that rule, traffic is sent to the "site busy" server associated to the second rule. Since the first rule measures all server traffic (including the "site busy" server) within the port to determine whether the traffic exceeds the threshold, as congestion decreases for the servers associated to the first rule, an unintentional result may occur where traffic continues to the "site busy" server because traffic within the port still exceeds the threshold of the first rule.
The server evaluation option is only valid for the following rules that make their decisions based upon the characteristics of the servers: total connections (per second) rule, active connections rule, and reserved bandwidth rule. The following are examples of the command syntax for the server evaluation option (evaluate):
ndcontrol rule [add] cluster:port:rule type reservedbandwidth evaluate value ndcontrol rule [set] cluster:port:rule evaluate value
(The value for evaluate is either port or rule. The default is port.)
This feature is available for the Dispatcher component. Generic Routing Encapsulation (GRE) is an Internet protocol specified in RFC 1701 and RFC 1702. Using GRE support, the Load Balancer encapsulates client IP packets inside IP/GRE packets and forwards them to server platforms such as OS/390 that support GRE. GRE support allows the Load Balancer to load balance packets to multiple server addresses associated with one MAC address. Earlier versions required one-to-one correspondence between MAC address and server address.
The Load Balancer implements GRE as part of its WAND (Wide Area Network Dispatcher) feature, thus providing wide area load balancing directly to any server systems that can unwrap the GRE packets. The Load Balancer does not need to be installed at the remote site if the remote servers support the encapsulated GRE packets. The Load Balancer encapsulates WAND packets with the GRE key field set to decimal value 3735928559.
For example, to add an OS/390 machine that supports GRE, define the OS/390 server within your Load Balancer configuration as if you are defining a WAND server in the cluster:port:server hierarchy. See "Configure wide area Dispatcher support" section in Chapter 8 of the IBM Network Dispatcher User's Guide Version 3.0 for Multiplatforms. No new ndcontrol commands are required to enable GRE support.
This feature is available for the Dispatcher and CBR components. With this enhancement, you have the ability to set the advisor's timeout values at which it detects a server has failed. The new failed-server timeout values (for connecttimeout and receivetimeout keywords) determine how long an advisor waits before reporting that either a connect or receive has failed.
To obtain the fastest failed-server detection, set the new advisor timeouts to the smallest value (one second), and set the advisor and manager interval time to the smallest value (one second). Note that if your environment experiences a moderate to high volume of traffic such that server response time increases, be careful not to set the timeout values too low, or the advisor may prematurely mark a busy server as failed.
The timeout values can be set from either the GUI or the command line. The following is the command syntax for connecttimeout and receivetimeout:
ndcontrol advisor connecttimeout advisor port timeoutseconds
ndcontrol advisor receivetimeout advisor port timeoutseconds
For example:
ndcontrol advisor connecttimeout http 80 1
ndcontrol advisor receivetimeout http 80 1
(Valid values for timeoutseconds are integers greater than 0. The default for timeoutseconds is three times the value specified for the advisor interval time.)
This feature is available for the Dispatcher and Content Based Routing (CBR) components. To remove a server from the Load Balancer configuration for any reason (updates, upgrades, service, etc.), you can use the ndcontrol manager quiesce command that has the effect of allowing existing connections to complete (without being severed) while disallowing all new connections to the quiesced server.
The quiesce enhancement extends the server quiesce function to recognize existing connections that have the affinity/sticky feature. For example, if you quiesce a server, and an existing connection has affinity to the server, then the Load Balancer can forward subsequent new connections from that client to the quiesced server as long as the subsequent new connections arrive before the stickytime expires. This enhancement provides a graceful, less abrupt, handling of sticky connections when quiescing servers. For instance, you can "gracefully" quiesce a server and then wait for the time where there is the least amount of traffic (perhaps early morning) to completely remove the server from the configuration.
A new optional keyword "now" has been added to the ndcontrol manager quiesce command:
ndcontrol manager quiesce address now
Only use quiesce "now" if you have stickytime set, and you want new connections sent to another server before stickytime expires. The now option determines how sticky connections are handled as follows:
If you do not specify "now," you allow existing connections to complete as well as forward subsequent new connections to the quiesced server from those clients with existing connections that are designated as sticky, as long as the quiesced server receives the new request before stickytime expires. (However, if you have not enabled the sticky/affinity feature, the quiesced server cannot receive any new connections.) This is the more graceful way to quiesce servers.
By specifying "now," you quiesce the server so that it allows existing connections to complete but disallows all new connections including subsequent new connections from those clients with existing connections that are designated as sticky. This more abrupt way to quiesce servers was the method provided in earlier releases.
You can view the quiesce status of the server from the GUI, or you can view it from the command line by issuing the ndcontrol server status command.
This feature is available for Dispatcher and ISS component. The ISS enhancement provides improved ISS DNS load balancing of Load Balancers in a two-tiered ISS configuration where an ISS DNS monitor determines how to load balance across a lower tier of Load Balancers. Previously for this type of load balancing (across a wide area network), the Load Balancer ran script files to furnish the ISS monitor with measurements based on the CPU load and memory of the Load Balancer machine, which is more a measure of a particular machine rather than the pool of servers behind it.
With this enhancement, Dispatcher provides a "self" advisor that collects load status information on backend servers. The self advisor specifically measures the connections per second rate on backend servers of the Load Balancer at the executor level. The self advisor writes the results to the ndloadstat file.
The Load Balancer also provides an external metric called ndload, which you add to the ISS configuration file when defining a ResourceType. The ISS agent on each Load Balancer machine runs its configuration that calls the external metric ndload. The ndload script extracts a string from the ndloadstat file and returns it to the ISS agent. Subsequently, each of the ISS agents (from each of the Load Balancers) returns the load status value to the ISS monitor for use in determining which Load Balancer to forward client requests.
The ndload executable file resides in the dispatcher directory for Load Balancer. For example, you can write the executable file name including pathname in the ISS configuration file as follows:
ResourceType NTScript Metric External "C:\Progra~1\IBM\nd\dispatcher\ndload.exe"
For this feature, ndcontrol report command displays a new statistic, connections per second rate, for the executor and cluster. You can view connections per second rate from the GUI, as well.
This feature is available for CBR with the Caching Proxy (WTE). The Load Balancer extends CBR to support SSL from the proxy to the server, which allows for complete SSL connections from the client to the server. In previous releases, CBR supported SSL from the client-to-proxy side, but not from the proxy-to-server side. CBR would receive an SSL transmission from the client and then decrypt the SSL request before proxying the request to an HTTP server. With SSL proxy-to-server support, you can define an SSL server in the CBR configuration to receive the SSL request from the client. This feature provides the ability to maintain a secure site, using CBR to load balance across secure (SSL) servers.
CBR will continue to support client-to-proxy in SSL and proxy-to-server in HTTP. To support this function, there is a new optional keyword "serverport" on the cbrcontrol port command. Use this keyword when you need to indicate that the port on the server is different from the incoming port from the client. You can view serverport value from the Port Status GUI panel ("Server(s) listening on port" field) or from the cbrcontrol port status command. An example of the cbrcontrol port command for serverport follows, where the client's port is 443 and the server port is 80:
cbrcontrol port [add | set] <cluster:443 serverport 80
(The port number for serverport can be any positive integer value. The default is the port number value of the incoming port from the client.)
Because CBR must be able to advise on an HTTP request for a server configured on SSL port 443, a special advisor "ssl2http" is provided. This advisor starts on port 443 (incoming port from the client) and advises on the server or servers configured for that port. If there are two clusters configured and each has port 443 configured, each with a different serverport, then a single instance of the advisor opens the appropriate port accordingly. The following is an example of this configuration:
Executor
Cluster 1
Port:443 serverport 80
Server 1
Server 2
Cluster 2
Port:443 serverport 8080
Server 3
Server 4
Manager
Advisor ssl2http 443
Display ndserver log status
This feature is available for the Dispatcher and CBR components. A new keyword (logstatus) has been added to the ndcontrol set and cbrcontrol set commands to display the server log settings (logging level and log size). An example of this command follows:
ndcontrol set logstatus
Display cluster configuration status
This feature is available for the Dispatcher component. The ndcontrol cluster status command returns an additional value, cluster configuration status. Cluster configuration status has information on whether the cluster is aliased (configured) on the NIC. Possible status results are: configured, unconfigured, or unavailable. A return status of unavailable results if the cluster did not respond. This information is also available from the GUI, under the Current Statistics tab within the Cluster panel.
Port-specific manager proportion enhancement
This feature is available for Dispatcher and CBR components. If the port-specific manager proportion is 0, when adding an advisor, the manager subtracts one each from the active and total connections proportions and sets the port-specific proportion to 2. If the system metric proportion is set to 100, when adding an advisor, the manager subtracts two from the system metric proportion, and adds two to the port-specific proportion. Note that each of the manager proportion values (active connections, new connections, port, system metrics) is expressed as a percentage of the total and therefore must always total 100.
New optional parameter for the ndload ISS external metric
This feature is available for the ISS component on Windows NT and Windows 2000. In the ISS configuration file, you can now specify the directory for the ndloadstat file as a parameter to the ndload ISS external metric. You only need to specify the directory if you start ISS from some other directory than the ISS directory (progra~1/ibm/nd/iss). An example of specifying the directory for the ndloadstat file on the external metric follows:
Metric EXTERNAL \progra~1\ibm\nd\dispatcher\ndload \\progra~1\\ibm\\nd\\dispatcher
Note that the first directory listed is for ndload. The second directory listed is to the ndloadstat file. The double backslashes are required as separators for the directory to the ndloadstat file. Also, the fully qualified path is necessary up to, but not including the ndloadstat file.
For Solaris, ibmnd configuration file enhancement
This feature is available for the Dispatcher component only on the Solaris platform. When removing an installed version of the Load Balancer, the ibmnd.conf file is renamed ibmnd.conf.bak to preserve configuration information. After re-installing the Load Balancer, you can rename ibmnd.conf.bak to ibmnd.conf.
The following directives have been added to the Caching Proxy v3.6 ibmproxy.conf file. Customers who perform a PTF upgrade of the Caching Proxy retain their original configuration file, which does not have these directives. These customers need to add new directives in order to enable new features and plug-ins. See About ibmproxy.conf for a discussion of the effects of a PTF upgrade on the ibmproxy.conf file.
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. (CyberPatrol directives can be edited by using the Configuration and Administration forms; see CyberPatrol filtering plug-in for configuration information.)
In the ibmproxy.conf file, directives used to configure Caching Proxy plug-in modules must be entered in the following format:
<MODULEBEGIN> plug-in name subdirective1 subdirective2 <MODULEEND>
Each plug-in 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 plug-in modules and some new features require API directives be added to the ibmproxy.conf file. Since the proxy server interacts with the plug-in 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 plug-in 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 plug-in. Add user-generated plug-in modules after those supplied with the product.
Use this directive to configure the Caching Proxy to recognize a WebSphere Application Server (that is configured with a Caching Proxy plug-in module) from which it can cache dynamic resources. The Caching Proxy pulls JSP results from the application server's dynamic cache. The Caching Proxy caches only contents from a 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. Detailed information is available in the JSP caching description in JSP and servlet response caching.
ExternalCacheManager External_Cache_Manager_ID Maximum_Expiry_Time
The following entry defines an external cache manager (a WebSphere Application Server) that is within the www.xyz.com domain and whose resources expire in 20 seconds or earlier.
ExternalCacheManager IBM-WTE-XYZ-1 20 seconds
None
Use this directive to enable or disable CyberPatrol filtering. It must be enclosed within the <MODULEBEGIN> CyberPatrol Content Filtering and <MODULEEND> directives.
Note that it is also necessary to add ServerInit and PreExit directives to the Caching Proxy configuration file to enable the plug-in. Detailed information is available in the CyberPatrol configuration description in CyberPatrol filtering plug-in.
FilterCyberPatrolOnOff [on | off]
FilterCyberPatrolOnOff off
Use this directive to set the filtering method. It must be enclosed within the <MODULEBEGIN> CyberPatrol Content Filtering and <MODULEEND> directives. The CyberNOT setting denies access to specified Web sites, while the CyberYES setting allows access only to specified Web sites.
FilterCyberPatrolList [cyberNOT | cyberYES]
FilterCyberPatrolList cyberYES
FilterCyberPatrolList cyberNOT
Use this directive to set filtering categories. It must be enclosed within the <MODULEBEGIN> CyberPatrol Content Filtering and <MODULEEND> directives.
Filtering categories are set using a rule mask, which is a hexidecimal code that describes all categories for which you want to filter. To construct rule masks from the category codes, add the codes for each individual category. Each code begins with 0x and includes four digits in hexidecimal format. Adding the digits in each position yields the rule mask. Possible categories to select and their codes are listed in CyberPatrol filtering plug-in. Details about the types of material included in each category are available from the SurfControl Web site, http://www.surfcontrol.com.
Note that if the CyberNOT filtering method is set, then access to Web sites in the filtered categories is blocked. If the CyberYES filtering method is set, then access is allowed to Web sites in the filtered categories only.
FilterCyberPatrolRuleMask hexidecimal_categories_code
This example describes a CyberYES filtering scheme that allows users access only to sites in the SurfPatrol categories Games & Toys, Arts, Books & Music, Oceans & Space, Pets, Animals & Dinosaurs, Vacations & Travel, Puzzles & Hobbies, Volunteer & Help, Kids, and Reference Materials.
FilterCyberPatrolList cyberYES FilterCyberPatrolRuleMask 0x2db3
None
Use this directive to set additional URLs or keywords to block or allow. It must be enclosed within the <MODULEBEGIN> CyberPatrol Content Filtering and <MODULEEND> directives.
If CyberNOT is active, additional sites and keywords you specify are blocked; if CyberYES is active, additional sites and keywords you specify are allowed. You can specify either a complete URL or a keyword. Using a keyword causes any URL containing that keyword to be filtered. Each URL or keyword requires a separate directive, and each directive must appear on its own line.
FilterAdditionalURL pattern_to_block_or_allow
FilterAdditionalURL ww.badsite.com FilterAdditionalURL xxx FilterAdditionalURL nudepic
None
Use this directive to set URLs to exclude from filtering. It must be enclosed within the <MODULEBEGIN> CyberPatrol Content Filtering and <MODULEEND> directives.
If CyberNOT is active, additional sites you specify are allowed; if CyberYES is active, additional sites you specify are blocked. This directive does not accept keywords, and the full URL must be specified in order to have the Web page excluded from filtering. Each URL or keyword requires a separate directive, and each directive must appear on its own line.
FilterExceptionlURL URL_to_exclude_from_filtering
FilterExceptionURL www.xyzmag.con/index.htm FilterExceptionURL www.xyzmag.com/events.htm
None
Use the following directives to configure the times of day and days of the week for filtering to be active. They must be enclosed within the <MODULEBEGIN> CyberPatrol Content Filtering and <MODULEEND> directives.
Setting more than one filtering time period is optional and can be used, as in the example that follows, to turn off filtering during nonworking hours. Only one time period needs to be set to enable filtering at all times, or in one continuous period. To configure filtering to be active at all times, set the start time to 00:00 and the end time to 24:00.
If two overlapping filter time periods are set, filtering continues from the earliest start time to the latest stop time.
FilterActivePeriodOneFrom 24_hour_time FilterActivePeriodOneUntil 24_hour_time FilterActivePeriodTwoFrom 24_hour_time FilterActivePeriodTwoUntil 24_hour_time FilterActiveWeekDays names_of_days
FilterActivePeriodOneFrom 08:30 FilterActivePeriodOneUntil 12:00 FilterActivePeriodTwoFrom 13:00 FilterActivePeriodTwoUntil 17:00 FilterActiveWeekDays Monday Tuesday Wednesday Thursday Friday
FilterActivePeriodOneFrom 00:00 FilterActivePeriodOneUntil 24:00 FilterActivePeriodTwoFrom 00:00 FilterActivePeriodTwoUntil 00:00 FilterActiveWeekDays Sunday Monday Tuesday Wednesday Thursday Friday Saturday
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 subdir