home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1997 December / Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso / rfc / rfc2186 < prev    next >
Text File  |  1997-09-05  |  19KB  |  508 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. Network Working Group                                         D. Wessels
  8. Request for Comments: 2186                                     K. Claffy
  9. Category: Informational                  National Laboratory for Applied
  10.                                                    Network Research/UCSD
  11.                                                           September 1997
  12.  
  13.                 Internet Cache Protocol (ICP), version 2
  14.  
  15. Status of this Memo
  16.  
  17.    This memo provides information for the Internet community.  This memo
  18.    does not specify an Internet standard of any kind.  Distribution of
  19.    this memo is unlimited.
  20.  
  21. Abstract
  22.  
  23.    This document describes version 2 of the Internet Cache Protocol
  24.    (ICPv2) as currently implemented in two World-Wide Web proxy cache
  25.    packages[3,5].  ICP is a lightweight message format used for
  26.    communicating among Web caches.  ICP is used to exchange hints about
  27.    the existence of URLs in neighbor caches.  Caches exchange ICP
  28.    queries and replies to gather information to use in selecting the
  29.    most appropriate location from which to retrieve an object.
  30.  
  31.    This document describes only the format and fields of ICP messages.
  32.    A companion document (RFC2187) describes the application of ICP to
  33.    Web caches.  Several independent caching implementations now use ICP,
  34.    and we consider it important to codify the existing practical uses of
  35.    ICP for those trying to implement, deploy, and extend its use for
  36.    their own purposes.
  37.  
  38. 1.  Introduction
  39.  
  40.    ICP is a message format used for communicating between Web caches.
  41.    Although Web caches use HTTP[1] for the transfer of object data,
  42.    caches benefit from a simpler, lighter communication protocol.  ICP
  43.    is primarily used in a cache mesh to locate specific Web objects in
  44.    neighboring caches.  One cache sends an ICP query to its neighbors.
  45.    The neighbors send back ICP replies indicating a "HIT" or a "MISS."
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58. Wessels & Claffy             Informational                      [Page 1]
  59.  
  60. RFC 2186                          ICP                     September 1997
  61.  
  62.  
  63.    In current practice, ICP is implemented on top of UDP, but there is
  64.    no requirement that it be limited to UDP.  We feel that ICP over UDP
  65.    offers features important to Web caching applications.  An ICP
  66.    query/reply exchange needs to occur quickly, typically within a
  67.    second or two.  A cache cannot wait longer than that before beginning
  68.    to retrieve an object.  Failure to receive a reply message most
  69.    likely means the network path is either congested or broken.  In
  70.    either case we would not want to select that neighbor.  As an
  71.    indication of immediate network conditions between neighbor caches,
  72.    ICP over a lightweight protocol such as UDP is better than one with
  73.    the overhead of TCP.
  74.  
  75.    In addition to its use as an object location protocol, ICP messages
  76.    can be used for cache selection.  Failure to receive a reply from a
  77.    cache may indicate a network or system failure.  The ICP reply may
  78.    include information that could assist selection of the most
  79.    appropriate source from which to retrieve an object.
  80.  
  81.    ICP was initially developed by Peter Danzig, et. al.  at the
  82.    University of Southern California as a central part of hierarchical
  83.    caching in the Harvest research project[3].
  84.  
  85. ICP Message Format
  86.  
  87.    The ICP message format consists of a 20-octet fixed header plus a
  88.    variable sized payload (see Figure 1).
  89.  
  90.    NOTE: All fields must be represented in network byte order.
  91.  
  92.    Opcode
  93.       One of the opcodes defined below.
  94.  
  95.    Version
  96.       The ICP protocol version number.  At the time of this writing,
  97.       both versions two and three are in use.  This document describes
  98.       only version two.  The version number field allows for future
  99.       development of this protocol.
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114. Wessels & Claffy             Informational                      [Page 2]
  115.  
  116. RFC 2186                          ICP                     September 1997
  117.  
  118.  
  119.    Message Length
  120.  
  121.      0                   1                   2                   3
  122.     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
  123.    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  124.    |     Opcode    |    Version    |         Message Length        |
  125.    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  126.    |                         Request Number                        |
  127.    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  128.    |                            Options                            |
  129.    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  130.    |                          Option Data                          |
  131.    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  132.    |                       Sender Host Address                     |
  133.    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  134.    |                                                               |
  135.    |                            Payload                            |
  136.    /                                                               /
  137.    /                                                               /
  138.    |                                                               |
  139.    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  140.  
  141.                      FIGURE 1: ICP message format.
  142.  
  143.       The total length (octets) of the ICP message.  ICP messages MUST
  144.       not exceed 16,384 octets in length.
  145.  
  146.    Request Number
  147.       An opaque identifier.  When responding to a query, this value must
  148.       be copied into the reply message.
  149.  
  150.    Options
  151.       A 32-bit field of option flags that allows extension of this
  152.       version of the protocol in certain, limited ways.  See "ICP Option
  153.       Flags" below.
  154.  
  155.    Option Data
  156.       A four-octet field to support optional features.  The following
  157.       ICP features make use of this field:
  158.  
  159.       The ICP_FLAG_SRC_RTT option uses the low 16-bits of Option Data to
  160.       return RTT measurements.  The ICP_FLAG_SRC_RTT option is further
  161.       described below.
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170. Wessels & Claffy             Informational                      [Page 3]
  171.  
  172. RFC 2186                          ICP                     September 1997
  173.  
  174.  
  175.    Sender Host Address
  176.       The IPv4 address of the host sending the ICP message.  This field
  177.       should probably not be trusted over what is  provided by getpeer-
  178.       name(), accept(), and recvfrom().  There is some ambiguity over
  179.       the original purpose of this field.  In practice it is not used.
  180.  
  181.    Payload
  182.       The contents of the Payload field vary depending on the Opcode,
  183.       but most often it contains a null-terminated URL string.
  184.  
  185. 2.  ICP Opcodes
  186.  
  187.    The following table shows currently defined ICP opcodes:
  188.  
  189.    Value    Name
  190.    -----    -----------------
  191.        0    ICP_OP_INVALID
  192.        1    ICP_OP_QUERY
  193.        2    ICP_OP_HIT
  194.        3    ICP_OP_MISS
  195.        4    ICP_OP_ERR
  196.      5-9    UNUSED
  197.       10    ICP_OP_SECHO
  198.       11    ICP_OP_DECHO
  199.    12-20    UNUSED
  200.       21    ICP_OP_MISS_NOFETCH
  201.       22    ICP_OP_DENIED
  202.       23    ICP_OP_HIT_OBJ
  203.  
  204.    ICP_OP_INVALID
  205.       A place holder to detect zero-filled or malformed messages.  A
  206.       cache must never intentionally send an ICP_OP_INVALID message.
  207.       ICP_OP_ERR should be used instead.
  208.  
  209.    ICP_OP_QUERY
  210.       A query message.  NOTE this opcode has a different payload format
  211.       than most of the others.  First is the requester's IPv4 address,
  212.       followed by a URL.  The Requester Host Address is not that of the
  213.       cache generating the ICP message, but rather the address of the
  214.       caches's client that originated the request.  The Requester Host
  215.       Address is often zero filled.  An ICP message with an all-zero
  216.       Requester Host Address address should be taken as one where the
  217.       requester address is not specified; it does not indicate a valid
  218.       IPv4 address.
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226. Wessels & Claffy             Informational                      [Page 4]
  227.  
  228. RFC 2186                          ICP                     September 1997
  229.  
  230.  
  231.       ICP_OP_QUERY payload format:
  232.  
  233.         0                   1                   2                   3
  234.        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
  235.       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  236.       |                     Requester Host Address                    |
  237.       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  238.       |                                                               |
  239.       /                       Null-Terminated URL                     /
  240.       /                                                               /
  241.       |                                                               |
  242.       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  243.  
  244.       In response to an ICP_OP_QUERY, the recipient must return one of:
  245.       ICP_OP_HIT, ICP_OP_MISS, ICP_OP_ERR, ICP_OP_MISS_NOFETCH,
  246.       ICP_OP_DENIED, or ICP_OP_HIT_OBJ.
  247.  
  248.    ICP_OP_SECHO
  249.       Similar to ICP_OP_QUERY, but for use in simulating a query to an
  250.       origin server.  When ICP is used to select the closest neighbor,
  251.       the origin server can be included in the algorithm by bouncing an
  252.       ICP_OP_SECHO message off it's echo port.  The payload is simply
  253.       the null-terminated URL.
  254.  
  255.       NOTE: the echo server will not interpret the data (i.e. we could
  256.       send it anything).  This opcode is used to tell the difference
  257.       between a legitimate query or response, random garbage, and an
  258.       echo response.
  259.  
  260.    ICP_OP_DECHO
  261.       Similar to ICP_OP_QUERY, but for use in simulating a query to a
  262.       cache which does not use ICP.  When ICP is used to choose the
  263.       closest neighbor, a non-ICP cache can be included in the algorithm
  264.       by bouncing an ICP_OP_DECHO message off it's echo port.  The
  265.       payload is simply the null-terminated URL.
  266.  
  267.       NOTE: one problem with this approach is that while a system's echo
  268.       port may be functioning perfectly, the cache software may not be
  269.       running at all.
  270.  
  271.    One of the following six ICP opcodes are sent in response to an
  272.    ICP_OP_QUERY message.  Unless otherwise noted, the payload must be
  273.    the null-terminated URL string.  Both the URL string and the Request
  274.    Number field must be exactly the same as from the ICP_OP_QUERY
  275.    message.
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282. Wessels & Claffy             Informational                      [Page 5]
  283.  
  284. RFC 2186                          ICP                     September 1997
  285.  
  286.  
  287.    ICP_OP_HIT
  288.       An ICP_OP_HIT response indicates that the requested URL exists in
  289.       this cache and that the requester is allowed to retrieve it.
  290.  
  291.    ICP_OP_MISS
  292.       An ICP_OP_MISS response indicates that the requested URL does not
  293.       exist in this cache.  The querying cache may still choose to fetch
  294.       the URL from the replying cache.
  295.  
  296.    ICP_OP_ERR
  297.       An ICP_OP_ERR response indicates some kind of error in parsing or
  298.       handling the query message (e.g. invalid URL).
  299.  
  300.    ICP_OP_MISS_NOFETCH
  301.       An ICP_OP_MISS_NOFETCH response indicates that this cache is up,
  302.       but is in a state where it does not want to handle cache misses.
  303.       An example of such a state is during a startup phase where a cache
  304.       might be rebuilding its object store.  A cache in such a mode may
  305.       wish to return ICP_OP_HIT for cache hits, but not ICP_OP_MISS for
  306.       misses.  ICP_OP_MISS_NOFETCH essentially means "I am up and
  307.       running, but please don't fetch this URL from me now."
  308.  
  309.       Note, ICP_OP_MISS_NOFETCH has a different meaning than
  310.       ICP_OP_MISS.  The ICP_OP_MISS reply is an invitation to fetch the
  311.       URL from the replying cache (if their relationship allows it), but
  312.       ICP_OP_MISS_NOFETCH is a request to NOT fetch the URL from the
  313.       replying cache.
  314.  
  315.    ICP_OP_DENIED
  316.       An ICP_OP_DENIED response indicates that the querying site is not
  317.       allowed to retrieve the named object from this cache.  Caches and
  318.       proxies may implement complex access controls.  This reply must be
  319.       be interpreted to mean "you are not allowed to request this
  320.       particular URL from me at this particular time."
  321.  
  322.       Caches receiving a high percentage of ICP_OP_DENIED replies are
  323.       probably misconfigured.  Caches should track percentage of all
  324.       replies which are ICP_OP_DENIED and disable a neighbor which
  325.       exceeds a certain threshold (e.g. 95% of 100 or more queries).
  326.  
  327.       Similarly, a cache should track the percent of ICP_OP_DENIED
  328.       messages that are sent to a given address.  If the percent of
  329.       denied messages exceeds a certain threshold (e.g. 95% of 100 or
  330.       more), the cache may choose to ignore all subsequent ICP_OP_QUERY
  331.       messages from that address until some sort of administrative
  332.       intervention occurs.
  333.  
  334.  
  335.  
  336.  
  337.  
  338. Wessels & Claffy             Informational                      [Page 6]
  339.  
  340. RFC 2186                          ICP                     September 1997
  341.  
  342.  
  343.    ICP_OP_HIT_OBJ
  344.       Just like an ICP_OP_HIT response, but the actual object data has
  345.       been included in this reply message.   Many requested objects are
  346.       small enough that it is possible to include them in the query
  347.       response and avoid the need to make a subsequent HTTP request for
  348.       the object.
  349.  
  350.       CAVEAT: ICP_OP_HIT_OBJ has some negative side effects which make
  351.       its use undesirable.  It transfers object data without HTTP and
  352.       therefore bypasses the standard HTTP processing, including
  353.       authorization and age validation.  Another negative side effect is
  354.       that ICP_OP_HIT_OBJ messages will often be much larger than the
  355.       path MTU, thereby causing fragmentation to occur on the UDP
  356.       packet.  For these reasons, use of ICP_OP_HIT_OBJ is NOT
  357.       recommended.
  358.  
  359.       A cache must not send an ICP_OP_HIT_OBJ unless the
  360.       ICP_FLAG_HIT_OBJ flag is set in the query message Options field.
  361.  
  362.       ICP_OP_HIT_OBJ payload format:
  363.  
  364.         0                   1                   2                   3
  365.        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
  366.       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  367.       |                                                               |
  368.       /                       Null-Terminated URL                     /
  369.       /                                                               /
  370.       |                                                               |
  371.       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  372.       |         Object Size           |                               |
  373.       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                               |
  374.       |                                                               |
  375.       /                           Object Data                         /
  376.       /                                                               /
  377.       |                                                               |
  378.       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  379.  
  380.  
  381.       The receiving application must check to make sure it actually
  382.       receives Object Size octets of data.  If it does not, then it
  383.       should treat the ICP_OP_HIT_OBJ reply as though it were a normal
  384.       ICP_OP_HIT.
  385.  
  386.       NOTE: the Object Size field does not necessarily begin on a 32-bit
  387.       boundary as shown in the diagram above.  It begins immediately
  388.       following the NULL byte of the URL string.
  389.  
  390.  
  391.  
  392.  
  393.  
  394. Wessels & Claffy             Informational                      [Page 7]
  395.  
  396. RFC 2186                          ICP                     September 1997
  397.  
  398.  
  399.    UNRECOGNIZED OPCODES
  400.       ICP messages with unrecognized or unused opcodes should be
  401.       ignored, i.e. no reply generated.  The application may choose to
  402.       note the anomalous behaviour in a log file.
  403.  
  404. 3.  ICP Option Flags
  405.  
  406.    0x80000000  ICP_FLAG_HIT_OBJ
  407.       This flag is set in an ICP_OP_QUERY message indicating that it is
  408.       okay to respond with an ICP_OP_HIT_OBJ message if the object data
  409.       will fit in the reply.
  410.  
  411.    0x40000000  ICP_FLAG_SRC_RTT
  412.       This flag is set in an ICP_OP_QUERY message indicating that the
  413.       requester would like the ICP reply to include the responder's
  414.       measured RTT to the origin server.
  415.  
  416.       Upon receipt of an ICP_OP_QUERY with ICP_FLAG_SRC_RTT bit set, a
  417.       cache should check an internal database of RTT measurements.  If
  418.       available, the RTT value MUST be expressed as a 16-bit integer, in
  419.       units of milliseconds.  If unavailable, the responder may either
  420.       set the RTT value to zero, or clear the ICP_FLAG_SRC_RTT bit in
  421.       the ICP reply.  The ICP reply MUST not be delayed while waiting
  422.       for the RTT measurement to occur.
  423.  
  424.       This flag is set in an ICP reply message (ICP_OP_HIT, ICP_OP_MISS,
  425.       ICP_OP_MISS_NOFETCH, or ICP_OP_HIT_OBJ) to indicate that the low
  426.       16-bits of the Option Data field contain the measured RTT to the
  427.       host given in the requested URL.  If ICP_FLAG_SRC_RTT is clear in
  428.       the query then it MUST also be clear in the reply.  If
  429.       ICP_FLAG_SRC_RTT is set in the query, then it may or may not be
  430.       set in the reply.
  431.  
  432. 4.  Security Considerations
  433.  
  434.    The security issues relating to ICP are discussed in the companion
  435.    document, RFC2187.
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450. Wessels & Claffy             Informational                      [Page 8]
  451.  
  452. RFC 2186                          ICP                     September 1997
  453.  
  454.  
  455. 5.  References
  456.  
  457.    [1] Fielding, R., et. al, "Hypertext Transfer Protocol -- HTTP/1.1",
  458.    RFC 2068, UC Irvine, January 1997.
  459.  
  460.    [2] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform Resource
  461.    Locators (URL)", RFC 1738, CERN, Xerox PARC, University of Minnesota,
  462.    December 1994.
  463.  
  464.    [3] Bowman M., Danzig P., Hardy D., Manber U., Schwartz M., and
  465.    Wessels D., "The Harvest Information Discovery and Access System",
  466.    Internet Research Task Force - Resource Discovery,
  467.    http://harvest.transarc.com/.
  468.  
  469.    [4] Wessels D., Claffy K., "ICP and the Squid Web Cache", National
  470.    Laboratory for Applied Network Research,
  471.    http://www.nlanr.net/~wessels/Papers/icp-squid.ps.gz
  472.  
  473.    [5] Wessels D., "The Squid Internet Object Cache", National
  474.    Laboratory for Applied Network Research,
  475.    http://squid.nlanr.net/Squid/
  476.  
  477. 6.  Acknowledgments
  478.  
  479.    The authors wish to thank Paul A Vixie <paul@vix.com> for providing
  480.    excellent feedback on this document.
  481.  
  482. 7.  Authors'  Addresses
  483.  
  484.    Duane Wessels
  485.    National Laboratory for Applied Network Research
  486.    10100 Hopkins Drive
  487.    La Jolla, CA 92093
  488.  
  489.    EMail: wessels@nlanr.net
  490.  
  491.  
  492.    K. Claffy
  493.    National Laboratory for Applied Network Research
  494.    10100 Hopkins Drive
  495.    La Jolla, CA 92093
  496.  
  497.    EMail: kc@nlanr.net
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506. Wessels & Claffy             Informational                      [Page 9]
  507.  
  508.