icpv2-protocol.txt

-

Network Working Group                                         D. Wessels
Internet-Draft                                                 K. Claffy
                                         National Laboratory for Applied
Obsoletes <draft-wessels-icp-v2-02.txt>            Network Research/UCSD
Expires: November 27, 1997                                   27 May 1997



                Internet Cache Protocol (ICP), version 2
                     <draft-wessels-icp-v2-03.txt>


Status of this Memo

   This document is an Internet-Draft. Internet-Drafts are working
   documents of the Internet Engineering Task Force (IETF), its areas,
   and its working groups. Note that other groups may also distribute
   working documents as Internet-Drafts.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time. It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as ``work in progress.''

   To learn the current status of any Internet-Draft, please check the
   ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow
   Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe),
   munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or
   ftp.isi.edu (US West Coast).

Abstract

   This draft document describes version 2 of the Internet Cache
   Protocol (ICPv2) as currently implemented in two World-Wide Web proxy
   cache packages[3,5].  ICP is a lightweight message format used for
   communicating among Web caches.  ICP is used to exchange hints about
   the existence of URLs in neighbor caches.  Caches exchange ICP
   queries and replies to gather information to use in selecting the
   most appropriate location from which to retrieve an object.

   This document describes only the format and fields of ICP messages.
   A companion document (RFCXXXX, <draft-wessels-icp-v2-appl-01.txt>)
   describes the application of ICP to Web caches.  Several independent
   caching implementations now use ICP, and we consider it important to
   codify the existing practical uses of ICP for those trying to
   implement, deploy, and extend its use for their own purposes.





Wessels                                                         [Page 1]

Internet-Draft                                             22 April 1997


1.  Introduction

   ICP is a message format used for communicating between Web caches.
   Although Web caches use HTTP[1] for the transfer of object data,
   caches benefit from a simpler, lighter communication protocol.  ICP
   is primarily used in a cache mesh to locate specific Web objects in
   neighboring caches.  One cache sends an ICP query to its neighbors.
   The neighbors send back ICP replies indicating a "HIT" or a "MISS."

   In current practice, ICP is implemented on top of UDP, but there is
   no requirement that it be limited to UDP.  We feel that ICP over UDP
   offers features important to Web caching applications.  An ICP
   query/reply exchange needs to occur quickly, typically within a sec-
   ond or two.  A cache cannot wait longer than that before beginning to
   retrieve an object.  Failure to receive a reply message most likely
   means the network path is either congested or broken.  In either case
   we would not want to select that neighbor.  As an indication of imme-
   diate network conditions between neighbor caches, ICP over a
   lightweight protocol such as UDP is better than one with the overhead
   of TCP.

   In addition to its use as an object location protocol, ICP messages
   can be used for cache selection.  Failure to receive a reply from a
   cache may indicate a network or system failure.  The ICP reply may
   include information that could assist selection of the most appropri-
   ate source from which to retrieve an object.

   ICP was initially developed by Peter Danzig, et. al.  at the Univer-
   sity of Southern California as a central part of hierarchical caching
   in the Harvest research project[3].

ICP Message Format

   The ICP message format consists of a 20-octet fixed header plus a
   variable sized payload (see Figure 1).

   NOTE: All fields must be represented in network byte order.

   Opcode
      One of the opcodes defined below.

   Version
      The ICP protocol version number.  At the time of this writing,
      both versions two and three are in use.  This document describes
      only version two.  The version number field allows for future
      development of this protocol.

   Message Length



Wessels                                                         [Page 2]

Internet-Draft                                             22 April 1997


     0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Opcode    |    Version    |         Message Length        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                         Request Number                        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                            Options                            |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                          Option Data                          |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                       Sender Host Address                     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                                                               |
   |                            Payload                            |
   /                                                               /
   /                                                               /
   |                                                               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                       FIGURE 1: ICP message format.

      The total length (octets) of the ICP message.  ICP messages MUST
      not exceed 16,384 octets in length.

   Request Number
      An opaque identifier.  When responding to a query, this value must
      be copied into the reply message.

   Options
      A 32-bit field of option flags that allows extension of this ver-
      sion of the protocol in certain, limited ways.  See ``ICP Option
      Flags'' below.

   Option Data
      A four-octet field to support optional features.  The following
      ICP features make use of this field:

      The ICP_FLAG_SRC_RTT option uses the low 16-bits of Option Data to
      return RTT measurements.  The ICP_FLAG_SRC_RTT option is further
      described below.

   Sender Host Address
      The IPv4 address of the host sending the ICP message.  This field
      should probably not be trusted over what is  provided by getpeer-
      name(), accept(), and recvfrom().  There is some ambiguity over
      the original purpose of this field.  In practice it is not used.




Wessels                                                         [Page 3]

Internet-Draft                                             22 April 1997


   Payload
      The contents of the Payload field vary depending on the Opcode,
      but most often it contains a null-terminated URL string.


2.  ICP Opcodes

The following table shows currently defined ICP opcodes:

   Value    Name
   -----    -----------------
       0    ICP_OP_INVALID
       1    ICP_OP_QUERY
       2    ICP_OP_HIT
       3    ICP_OP_MISS
       4    ICP_OP_ERR
     5-9    UNUSED
      10    ICP_OP_SECHO
      11    ICP_OP_DECHO
   12-20    UNUSED
      21    ICP_OP_MISS_NOFETCH
      22    ICP_OP_DENIED
      23    ICP_OP_HIT_OBJ

   ICP_OP_INVALID
      A place holder to detect zero-filled or malformed messages.  A
      cache must never intentionally send an ICP_OP_INVALID message.
      ICP_OP_ERR should be used instead.

   ICP_OP_QUERY
      A query message.  NOTE this opcode has a different payload format
      than most of the others.  First is the requester's IPv4 address,
      followed by a URL.  The Requester Host Address is not that of the
      cache generating the ICP message, but rather the address of the
      caches's client that originated the request.  The Requester Host
      Address is often zero filled.  An ICP message with an all-zero
      Requester Host Address address should be taken as one where the
      requester address is not specified; it does not indicate a valid
      IPv4 address.












Wessels                                                         [Page 4]

Internet-Draft                                             22 April 1997


      ICP_OP_QUERY payload format:

        0                   1                   2                   3
       0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
      |                     Requester Host Address                    |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
      |                                                               |
      /                       Null-Terminated URL                     /
      /                                                               /
      |                                                               |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


      In response to an ICP_OP_QUERY, the recipient must return one of:
      ICP_OP_HIT, ICP_OP_MISS, ICP_OP_ERR, ICP_OP_MISS_NOFETCH,
      ICP_OP_DENIED, or ICP_OP_HIT_OBJ.

   ICP_OP_SECHO
      Similar to ICP_OP_QUERY, but for use in simulating a query to an
      origin server.  When ICP is used to select the closest neighbor,
      the origin server can be included in the algorithm by bouncing an
      ICP_OP_SECHO message off it's echo port.  The payload is simply
      the null-terminated URL.