idnits 2.17.1 draft-wessels-icp-v2-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-24) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == Mismatching filename: the document gives the document name as 'draft-wessels-icp-v2-01', but the file name used is 'draft-wessels-icp-v2-02' == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 101: '...of the ICP message. ICP messages MUST...' RFC 2119 keyword, line 322: '...e, the RTT value MUST be expressed as ...' RFC 2119 keyword, line 325: '.... The ICP reply MUST not be delayed w...' RFC 2119 keyword, line 332: '...he query then it MUST also be clear in...' Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 123 has weird spacing: '...what is provi...' == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: Message Length The total length (octets) of the ICP message. ICP messages MUST not exceed 16,384 octets in length. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: 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. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (22 April 1997) is 9864 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: '2' is defined on line 346, but no explicit reference was found in the text == Unused Reference: '3' is defined on line 350, but no explicit reference was found in the text == Unused Reference: '4' is defined on line 355, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2068 (ref. '1') (Obsoleted by RFC 2616) ** Obsolete normative reference: RFC 1738 (ref. '2') (Obsoleted by RFC 4248, RFC 4266) -- Possible downref: Non-RFC (?) normative reference: ref. '3' -- Possible downref: Non-RFC (?) normative reference: ref. '4' Summary: 11 errors (**), 0 flaws (~~), 8 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group D. Wessels 2 Internet-Draft National Laboratory for Applied 3 Obsoletes Network Research/UCSD 4 Expires: November 22, 1997 22 April 1997 6 Internet Cache Protocol (ICP), version 2 7 9 Status of this Memo 11 This document is an Internet-Draft. Internet-Drafts are working 12 documents of the Internet Engineering Task Force (IETF), its areas, 13 and its working groups. Note that other groups may also distribute 14 working documents as Internet-Drafts. 16 Internet-Drafts are draft documents valid for a maximum of six months 17 and may be updated, replaced, or obsoleted by other documents at any 18 time. It is inappropriate to use Internet-Drafts as reference 19 material or to cite them other than as ``work in progress.'' 21 To learn the current status of any Internet-Draft, please check the 22 ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow 23 Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), 24 munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or 25 ftp.isi.edu (US West Coast). 27 Abstract 29 This draft document describes the Internet Cache Protocol (ICP) as 30 currently implemented in a couple of World-Wide Web proxy cache 31 packages. A companion document (RFCXXXX, ) describes the application of ICP to Web caches. ICP 33 was initially developed by Peter Danzig, et. al. at the University of 34 Southern California. It evolved as an important part of hierarchical 35 caching on the Harvest research project. 37 1. Introduction 38 ICP is a message format used for communicating between Web caches. 39 Although Web caches use HTTP[1] for the transfer of object data, 40 caches benefit from a simpler, lighter communication protocol. ICP 41 is primarily used in a cache mesh to locate specific Web objects in 42 neighbor caches. One cache will send an ICP query to its neighbors. 43 The neighbors will send back ICP replies indicating a ``HIT'' or a 44 ``MISS.'' 46 In current practice, ICP is implemented on top of UDP, but there is 47 no requirement that it be limited to UDP. We feel that ICP over UDP 48 offers features important to Web caching applications. An ICP 49 query/reply exchange needs to occur quickly, typically within a sec- 50 ond or two. A cache cannot wait longer than that before beginning to 51 retrieve an object. Failure to receive a reply message most likely 52 means the network path is either congested or broken. In either case 53 we would not want to select that neighbor. As an indication of imme- 54 diate network conditions between neighbor caches, ICP over a 55 lightweight protocol such as UDP is better than one with the overhead 56 of TCP. 58 In addition to its use as an object location protocol, ICP messages 59 can be used for cache selection. Failure to receive a reply from a 60 cache may indicate a network or system failure. The ICP reply may 61 include information that could assist selection of the most appropri- 62 ate source from which to retrieve an object. 64 ICP Message Format 66 The ICP message format consists of a 20-octet fixed header plus a 67 variable sized payload: 69 0 1 2 3 70 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 71 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 72 | Opcode | Version | Message Length | 73 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 74 | Request Number | 75 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 76 | Options | 77 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 78 | Option Data | 79 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 80 | Sender Host Address | 81 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 82 | | 83 | Payload | 84 / / 85 / / 86 | | 87 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 89 NOTE: All fields must be represented in network byte order. 91 Opcode 92 One of the opcodes defined below. 94 Version 95 The ICP protocol version number. At the time of this writing, 96 both versions two and three are in use. This document describes 97 only version two. The version number field allows for future 98 development of this protocol. 100 Message Length 101 The total length (octets) of the ICP message. ICP messages MUST 102 not exceed 16,384 octets in length. 104 Request Number 105 An opaque identifier. When responding to a query, this value must 106 be copied into the reply message. 108 Options 109 A 32-bit field of option flags that allows extension of this ver- 110 sion of the protocol in certain, limited ways. See ``ICP Option 111 Flags'' below. 113 Option Data 114 A four-octet field to support optional features. The following 115 ICP features make use of this field: 117 The ICP_FLAG_SRC_RTT option uses the low 16-bits of Option Data to 118 return RTT measurements. The ICP_FLAG_SRC_RTT option is further 119 described below. 121 Sender Host Address 122 The IPv4 address of the host sending the ICP message. This field 123 should probably not be trusted over what is provided by getpeer- 124 name(), accept(), and recvfrom(). There is some ambiguity over 125 the original purpose of this field. In practice it is not used. 127 Payload 128 The contents of the Payload field vary depending on the Opcode, 129 but most often it contains a null-terminated URL string. 131 2. ICP Opcodes 133 The following table shows currently defined ICP opcodes: 135 Value Name 136 ----- ----------------- 137 0 ICP_OP_INVALID 138 1 ICP_OP_QUERY 139 2 ICP_OP_HIT 140 3 ICP_OP_MISS 141 4 ICP_OP_ERR 142 5-9 UNUSED 143 10 ICP_OP_SECHO 144 11 ICP_OP_DECHO 145 12-20 UNUSED 146 21 ICP_OP_MISS_NOFETCH 147 22 ICP_OP_DENIED 148 23 ICP_OP_HIT_OBJ 150 ICP_OP_INVALID 151 A place holder to detect zero-filled or malformed messages. A 152 cache must never intentionally send an ICP_OP_INVALID message. 153 ICP_OP_ERR should be used instead. 155 ICP_OP_QUERY 156 A query message. NOTE this opcode has a different payload format 157 than most of the others. First is the requester's IPv4 address, 158 followed by a URL. The Requester Host Address is not that of the 159 cache generating the ICP message, but rather the address of the 160 caches's client that originated the request. The Requester Host 161 Address is often zero filled. An ICP message with an all-zero 162 Requester Host Address address should be taken as one where the 163 requester address is not specified; it does not indicate a valid 164 IPv4 address. 166 ICP_OP_QUERY payload format: 168 0 1 2 3 169 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 170 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 171 | Requester Host Address | 172 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 173 | | 174 / Null-Terminated URL / 175 / / 176 | | 177 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 178 In response to an ICP_OP_QUERY, the recipient must return one of: 179 ICP_OP_HIT, ICP_OP_MISS, ICP_OP_ERR, ICP_OP_MISS_NOFETCH, 180 ICP_OP_DENIED, or ICP_OP_HIT_OBJ. 182 ICP_OP_SECHO 183 Similar to ICP_OP_QUERY, but for use in simulating a query to an 184 origin server. When ICP is used to select the closest neighbor, 185 the origin server can be included in the algorithm by bouncing an 186 ICP_OP_SECHO message off it's echo port. The payload is simply 187 the null-terminated URL. 189 NOTE: the echo server will not interpret the data (i.e. we could 190 send it anything). This opcode is used to tell the difference 191 between a legitimate query or response, random garbage, and an 192 echo response. 194 ICP_OP_DECHO 195 Similar to ICP_OP_QUERY, but for use in simulating a query to a 196 cache which does not use ICP. When ICP is used to choose the 197 closest neighbor, a non-ICP cache can be included in the algorithm 198 by bouncing an ICP_OP_DECHO message off it's echo port. The pay- 199 load is simply the null-terminated URL. 201 NOTE: one problem with this approach is that while a system's echo 202 port may be functioning perfectly, the cache software may not be 203 running at all. 205 One of the following six ICP opcodes are sent in response to an 206 ICP_OP_QUERY message. Unless otherwise noted, the payload must be 207 the null-terminated URL string. Both the URL string and the Request 208 Number field must be exactly the same as from the ICP_OP_QUERY mes- 209 sage. 211 ICP_OP_HIT 212 An ICP_OP_HIT response indicates that the requested URL exists in 213 this cache and that the requester is allowed to retrieve it. 215 ICP_OP_MISS 216 An ICP_OP_MISS response indicates that the requested URL does not 217 exist in this cache. The querying cache may still choose to fetch 218 the URL from the replying cache. 220 ICP_OP_ERR 221 An ICP_OP_ERR response indicates some kind of error in parsing or 222 handling the query message (e.g. invalid URL). 224 ICP_OP_MISS_NOFETCH 225 An ICP_OP_MISS_NOFETCH response indicates that this cache is up, 226 but is in a state where it does not want to handle cache misses. 227 An example of such a state is during a startup phase where a cache 228 might be rebuilding its object store. A cache in such a mode may 229 wish to return ICP_OP_HIT for cache hits, but not ICP_OP_MISS for 230 misses. ICP_OP_MISS_NOFETCH essentially means ``I am up and run- 231 ning, but please don't fetch this URL from me now.'' 233 Note, ICP_OP_MISS_NOFETCH has a different meaning than 234 ICP_OP_MISS. The ICP_OP_MISS reply is an invitation to fetch the 235 URL from the replying cache (if their relationship allows it), but 236 ICP_OP_MISS_NOFETCH is a request to NOT fetch the URL from the 237 replying cache. 239 ICP_OP_DENIED 240 An ICP_OP_DENIED response indicates that the querying site is not 241 allowed to retrieve the named object from this cache. Caches and 242 proxies may implement complex access controls. This reply must be 243 be interpreted to mean ``you are not allowed to request this par- 244 ticular URL from me at this particular time.'' 246 Caches receiving a high percentage of ICP_OP_DENIED replies are 247 probably misconfigured. Caches should track percentage of all 248 replies which are ICP_OP_DENIED and disable a neighbor which 249 exceeds a certain threshold (e.g. 95% of 100 or more queries). 251 Similarly, a cache should track the percent of ICP_OP_DENIED mes- 252 sages that are sent to a given address. If the percent of denied 253 messages exceeds a certain threshold (e.g. 95% of 100 or more), 254 the cache may choose to ignore all subsequent ICP_OP_QUERY mes- 255 sages from that address until some sort of administrative inter- 256 vention occurs. 258 ICP_OP_HIT_OBJ 259 Just like an ICP_OP_HIT response, but the actual object data has 260 been included in this reply message. Many requested objects are 261 small enough that it is possible to include them in the query 262 response and avoid the need to make a subsequent HTTP request for 263 the object. 265 CAVEAT: ICP_OP_HIT_OBJ has some negative side effects which make 266 its use undesirable. It transfers object data without HTTP and 267 therefore bypasses the standard HTTP processing, including autho- 268 rization and age validation. Another negative side effect is that 269 ICP_OP_HIT_OBJ messages will often be much larger than the path 270 MTU, thereby causing fragmentation to occur on the UDP packet. 271 For these reasons, use of ICP_OP_HIT_OBJ is NOT recommended. 273 A cache must not send an ICP_OP_HIT_OBJ unless the 274 ICP_FLAG_HIT_OBJ flag is set in the query message Options field. 276 ICP_OP_HIT_OBJ payload format: 278 0 1 2 3 279 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 280 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 281 | | 282 / Null-Terminated URL / 283 / / 284 | | 285 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 286 | Object Size | | 287 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 288 | | 289 / Object Data / 290 / / 291 | | 292 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 294 The receiving application must check to make sure it actually 295 receives Object Size octets of data. If it does not, then it 296 should treat the ICP_OP_HIT_OBJ reply as though it were a normal 297 ICP_OP_HIT. 299 NOTE: the Object Size field does not necessarily begin on a 32-bit 300 boundary as shown in the diagram above. It begins immediately 301 following the NULL byte of the URL string. 303 UNRECOGNIZED OPCODES 304 ICP messages with unrecognized or unused opcodes should be 305 ignored, i.e. no reply generated. The application may choose to 306 note the anomalous behaviour in a log file. 308 3. ICP Option Flags 310 0x80000000 ICP_FLAG_HIT_OBJ 311 This flag is set in an ICP_OP_QUERY message indicating that it is 312 okay to respond with an ICP_OP_HIT_OBJ message if the object data 313 will fit in the reply. 315 0x40000000 ICP_FLAG_SRC_RTT 316 This flag is set in an ICP_OP_QUERY message indicating that the 317 requester would like the ICP reply to include the responder's mea- 318 sured RTT to the origin server. 320 Upon receipt of an ICP_OP_QUERY with ICP_FLAG_SRC_RTT bit set, a 321 cache should check an internal database of RTT measurements. If 322 available, the RTT value MUST be expressed as a 16-bit integer, in 323 units of milliseconds. If unavailable, the responder may either 324 set the RTT value to zero, or clear the ICP_FLAG_SRC_RTT bit in 325 the ICP reply. The ICP reply MUST not be delayed while waiting 326 for the RTT measurement to occur. 328 This flag is set in an ICP reply message (ICP_OP_HIT, ICP_OP_MISS, 329 ICP_OP_MISS_NOFETCH, or ICP_OP_HIT_OBJ) to indicate that the low 330 16-bits of the Option Data field contain the measured RTT to the 331 host given in the requested URL. If ICP_FLAG_SRC_RTT is clear in 332 the query then it MUST also be clear in the reply. If 333 ICP_FLAG_SRC_RTT is set in the query, then it may or may not be 334 set in the reply. 336 4. Security Considerations 338 The security issues relating to ICP are discussed in the companion 339 document, RFCXXXX (). 341 5. References 343 [1] Fielding, R., et. al, "Hypertext Transfer Protocol -- HTTP/1.1", 344 RFC 2068, UC Irvine, January 1997. 346 [2] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform Resource 347 Locators (URL)", RFC 1738, CERN, Xerox PARC, University of Minnesota, 348 December 1994. 350 [3] Bowman M., Danzig P., Hardy D., Manber U., Schwartz M., and Wes- 351 sels D., "The Harvest Information Discovery and Access System", 352 Internet Research Task Force - Resource Discovery, http://har- 353 vest.transarc.com/. 355 [4] Wessels D., Claffy K., "ICP and the Squid Web Cache", National 356 Laboratory for Applied Network Research, http://www.nlanr.net/~wes- 357 sels/Papers/icp-squid.ps.gz 359 6. Acknowledgments 361 Paul A Vixie 363 7. Author's Address: 365 Duane Wessels 366 National Laboratory for Applied Network Research 367 wessels@nlanr.net 369 K Claffy 370 National Laboratory for Applied Network Research 371 kc@nlanr.net