ICPFilter reference manual

# ICP Filter

The ICP client side filter add support for the Internet Cache Protocol to the Jigsaw HTTP client side implementation. This support can be used both by browsers (such as HotJava, check the FAQ), or by proxies (the typical case).

In brief, ICP allows several proxies to cooperate by exchanging informations about what they currently have in their local cache. Jigsaw's ICP implementation should be compatible with other ICP capable proxies (such as Squid), even though it doesn't make use of all the features of the underlying protocol (in fact, it implements what can be implemented while still remaining compliant with the HTTP/1.1 protocol specification).

Warning: Jigsaw doesn't come with the appropriate support for editing the ICP filter properties from the `/Admin/Properties` resource; this means that you will have to manually edit your Jigsaw configuration file in order to set the properties relevant to that filter. This file is usually named `config/http-server.props` if not, you probably know already what we are talking about.

### ICP Configuration File

This filter uses a configuration file, to know about the proxies it cooperates with. The syntax for this rule file is defined by the following BNF:

    rule-file := *(rules)
    rules     := (comment|host-description)
    comment   := '#' <chars up EOL>
    host-description := host SPACES port spaces url EOL
    host      := <valid Internet host name>
    port      := <valid UDP port number>
    url       := <URL locating the proxy to use for that host/port>
    SPACES    := *(' '|'\t')
    EOL       := '\r' | '\r\n' | '\n'

A sample ICP configuration file looks like:

    # Sample ICP configuration file
    # -----------------------------
    # First neighbour:
    icp.host1.com 10345 http://icp.host1.com:8080/
    # Second neighbour:
    icp.host2.com 10345 http://icp.host2.com:8080/

After parsing such a configuration file, the ICP filter, will register both hosts as neighbours. When a request comes in for some document, the filter sends a UDP packet to both hosts (it knows about their namee, and the port they are listening on through the first two fields of the configuration file). It then waits for some positive answer, if such an answer arrives, it finally looks it up (matching the UDP sender address with one of the above declared hosts), and use the appropriate URL as a proxy address.

To setup a nice cache hierarchy, one can use a conjunction of the ProxyDispatcher filter, the CacheFilter and the ICP filter. The starting point for setting up such a config, is to set the HttpManager filters property to:

    w3c.www.protocol.http.filters=w3c.www.protocol.http.proxy.ProxyDispatcher \
         |w3c.www.protocol.http.cache.CacheFilter \
         |w3c.www.protocol.http.icp.ICPFilter

(the \ character indicates that the line is splitted for best reading, they should not appear in the property value - which should be written as a single line). Note that in this setting the order in which you declare the filters is indeed important.

## Properties

The ICPFilter defines the following properties:

- w3c.www.protocol.http.icp.debug
- w3c.www.protocol.http.icp.config
- w3c.www.protocol.http.icp.port
- w3c.www.protocol.http.icp.timeout
- w3c.www.protocol.http.icp.disable-cache

`w3c.www.protocol.http.icp.debug`

semantics
  When set to true, this property will make the ICP filter emit some (hopefully) interesting traces.
type
  A boolean property.
default value
  This property defaults to false.

`w3c.www.protocol.http.icp.config`

semantics
  The name of the rule file for ICP
type
  A File property (it's value should provide a path to an existing file)
default value
  This property has no default value, and must be set for the ICP filter to be activated.

`w3c.www.protocol.http.icp.port`

semantics
  The UDP port number that filter should use to communicate with cooperating proxies. This port number is the one the filter will be listening at for requests from other (cooperating proxies).
type
  An integer property (it's value should be a valid UDP port number)
default value
  This property has no default value and must be set for the ICP filter to be activated.

`w3c.www.protocol.http.icp.timeout`

semantics
  The number of milliseconds the filter should wait for replies from cooperating proxies, before estimating that none of them is available to answer its query.
type
  An integer property (it's value should be a valid number of milliseconds)
default value
  This property defaults to 500 ms.

`w3c.www.protocol.http.icp.disable-cache`

semantics
  Disable the caching of documents retreived through a neighbour proxy. If you're making a set of local proxies cooperate, this flag will ensure that no two close proxy will cache the same page.
type
  A boolean property.
default value
  This property defaults to true

Jigsaw Team
$Id: w3c.www.protocol.http.icp.ICPFilter.html,v 1.1 1997/02/11 19:46:53 abaird Exp $