icpv2-protocol.txt

-

      NOTE: the echo server will not interpret the data (i.e. we could
      send it anything).  This opcode is used to tell the difference
      between a legitimate query or response, random garbage, and an
      echo response.

   ICP_OP_DECHO
      Similar to ICP_OP_QUERY, but for use in simulating a query to a
      cache which does not use ICP.  When ICP is used to choose the
      closest neighbor, a non-ICP cache can be included in the algorithm
      by bouncing an ICP_OP_DECHO message off it's echo port.  The pay-
      load is simply the null-terminated URL.

      NOTE: one problem with this approach is that while a system's echo
      port may be functioning perfectly, the cache software may not be
      running at all.

   One of the following six ICP opcodes are sent in response to an
   ICP_OP_QUERY message.  Unless otherwise noted, the payload must be
   the null-terminated URL string.  Both the URL string and the Request
   Number field must be exactly the same as from the ICP_OP_QUERY mes-
   sage.

   ICP_OP_HIT



Wessels                                                         [Page 5]

Internet-Draft                                             22 April 1997


      An ICP_OP_HIT response indicates that the requested URL exists in
      this cache and that the requester is allowed to retrieve it.

   ICP_OP_MISS
      An ICP_OP_MISS response indicates that the requested URL does not
      exist in this cache.  The querying cache may still choose to fetch
      the URL from the replying cache.

   ICP_OP_ERR
      An ICP_OP_ERR response indicates some kind of error in parsing or
      handling the query message (e.g. invalid URL).

   ICP_OP_MISS_NOFETCH
      An ICP_OP_MISS_NOFETCH response indicates that this cache is up,
      but is in a state where it does not want to handle cache misses.
      An example of such a state is during a startup phase where a cache
      might be rebuilding its object store.  A cache in such a mode may
      wish to return ICP_OP_HIT for cache hits, but not ICP_OP_MISS for
      misses.  ICP_OP_MISS_NOFETCH essentially means ``I am up and run-
      ning, but please don't fetch this URL from me now.''

      Note, ICP_OP_MISS_NOFETCH has a different meaning than
      ICP_OP_MISS.  The ICP_OP_MISS reply is an invitation to fetch the
      URL from the replying cache (if their relationship allows it), but
      ICP_OP_MISS_NOFETCH is a request to NOT fetch the URL from the
      replying cache.

   ICP_OP_DENIED
      An ICP_OP_DENIED response indicates that the querying site is not
      allowed to retrieve the named object from this cache.  Caches and
      proxies may implement complex access controls.  This reply must be
      be interpreted to mean ``you are not allowed to request this par-
      ticular URL from me at this particular time.''

      Caches receiving a high percentage of ICP_OP_DENIED replies are
      probably misconfigured.  Caches should track percentage of all
      replies which are ICP_OP_DENIED and disable a neighbor which
      exceeds a certain threshold (e.g. 95% of 100 or more queries).

      Similarly, a cache should track the percent of ICP_OP_DENIED mes-
      sages that are sent to a given address.  If the percent of denied
      messages exceeds a certain threshold (e.g. 95% of 100 or more),
      the cache may choose to ignore all subsequent ICP_OP_QUERY mes-
      sages from that address until some sort of administrative inter-
      vention occurs.

   ICP_OP_HIT_OBJ
      Just like an ICP_OP_HIT response, but the actual object data has



Wessels                                                         [Page 6]

Internet-Draft                                             22 April 1997


      been included in this reply message.   Many requested objects are
      small enough that it is possible to include them in the query
      response and avoid the need to make a subsequent HTTP request for
      the object.

      CAVEAT: ICP_OP_HIT_OBJ has some negative side effects which make
      its use undesirable.  It transfers object data without HTTP and
      therefore bypasses the standard HTTP processing, including autho-
      rization and age validation.  Another negative side effect is that
      ICP_OP_HIT_OBJ messages will often be much larger than the path
      MTU, thereby causing fragmentation to occur on the UDP packet.
      For these reasons, use of ICP_OP_HIT_OBJ is NOT recommended.

      A cache must not send an ICP_OP_HIT_OBJ unless the
      ICP_FLAG_HIT_OBJ flag is set in the query message Options field.

      ICP_OP_HIT_OBJ 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
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
      |                                                               |
      /                       Null-Terminated URL                     /
      /                                                               /
      |                                                               |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
      |         Object Size           |                               |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                               |
      |                                                               |
      /                           Object Data                         /
      /                                                               /
      |                                                               |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


      The receiving application must check to make sure it actually
      receives Object Size octets of data.  If it does not, then it
      should treat the ICP_OP_HIT_OBJ reply as though it were a normal
      ICP_OP_HIT.

      NOTE: the Object Size field does not necessarily begin on a 32-bit
      boundary as shown in the diagram above.  It begins immediately
      following the NULL byte of the URL string.

   UNRECOGNIZED OPCODES
      ICP messages with unrecognized or unused opcodes should be
      ignored, i.e. no reply generated.  The application may choose to
      note the anomalous behaviour in a log file.



Wessels                                                         [Page 7]

Internet-Draft                                             22 April 1997


3.  ICP Option Flags

   0x80000000  ICP_FLAG_HIT_OBJ
      This flag is set in an ICP_OP_QUERY message indicating that it is
      okay to respond with an ICP_OP_HIT_OBJ message if the object data
      will fit in the reply.

   0x40000000  ICP_FLAG_SRC_RTT
      This flag is set in an ICP_OP_QUERY message indicating that the
      requester would like the ICP reply to include the responder's mea-
      sured RTT to the origin server.

      Upon receipt of an ICP_OP_QUERY with ICP_FLAG_SRC_RTT bit set, a
      cache should check an internal database of RTT measurements.  If
      available, the RTT value MUST be expressed as a 16-bit integer, in
      units of milliseconds.  If unavailable, the responder may either
      set the RTT value to zero, or clear the ICP_FLAG_SRC_RTT bit in
      the ICP reply.  The ICP reply MUST not be delayed while waiting
      for the RTT measurement to occur.

      This flag is set in an ICP reply message (ICP_OP_HIT, ICP_OP_MISS,
      ICP_OP_MISS_NOFETCH, or ICP_OP_HIT_OBJ) to indicate that the low
      16-bits of the Option Data field contain the measured RTT to the
      host given in the requested URL.  If ICP_FLAG_SRC_RTT is clear in
      the query then it MUST also be clear in the reply.  If
      ICP_FLAG_SRC_RTT is set in the query, then it may or may not be
      set in the reply.


4.  Security Considerations

   The security issues relating to ICP are discussed in the companion
   document, RFCXXXX (<draft-wessels-icp-v2-appl-01.txt>).


5.  References

   [1] Fielding, R., et. al, "Hypertext Transfer Protocol -- HTTP/1.1",
   RFC 2068, UC Irvine, January 1997.

   [2] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform Resource
   Locators (URL)", RFC 1738, CERN, Xerox PARC, University of Minnesota,
   December 1994.

   [3] Bowman M., Danzig P., Hardy D., Manber U., Schwartz M., and Wes-
   sels D., "The Harvest Information Discovery and Access System",
   Internet Research Task Force - Resource Discovery, http://har-
   vest.transarc.com/.



Wessels                                                         [Page 8]

Internet-Draft                                             22 April 1997


   [4] Wessels D., Claffy K., "ICP and the Squid Web Cache", National
   Laboratory for Applied Network Research, http://www.nlanr.net/~wes-
   sels/Papers/icp-squid.ps.gz

   [5] Wessels D., "The Squid Internet Object Cache", National Labora-
   tory for Applied Network Research, http://squid.nlanr.net/Squid/


6.  Acknowledgments

   The authors wish to thank Paul A Vixie <[e-mail]> for
   providing excellent feedback on this document.


7.  Author's  Addresses:

   Duane Wessels
   National Laboratory for Applied Network Research
   10100 Hopkins Drive
   La Jolla, CA 92093
   [e-mail]

   K Claffy
   National Laboratory for Applied Network Research
   10100 Hopkins Drive
   La Jolla, CA 92093
   [e-mail]
























Wessels                                                         [Page 9]