idnits 2.17.1 draft-bryan-ftp-range-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (December 20, 2010) is 4876 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) -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Bryan 3 Internet-Draft T. Tsujikawa 4 Intended status: Standards Track D. Stenberg 5 Expires: June 23, 2011 December 20, 2010 7 File Transfer Protocol RANG Command for Byte Ranges 8 draft-bryan-ftp-range-00 10 Abstract 12 The File Transfer Protocol offers REST, to designate a starting point 13 for a transfer, but does not currently offer any method to specify an 14 end point. This document specifies a new FTP RANG command to be used 15 by clients to designate a start and end point for STREAM mode 16 transfers with RETR. 18 Status of this Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on June 23, 2011. 35 Copyright Notice 37 Copyright (c) 2010 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 2. Document Conventions . . . . . . . . . . . . . . . . . . . . . 3 54 2.1. Basic Tokens . . . . . . . . . . . . . . . . . . . . . . . 4 55 2.2. Server Replies . . . . . . . . . . . . . . . . . . . . . . 4 56 3. Byte Ranges in STREAM Mode . . . . . . . . . . . . . . . . . . 4 57 4. The RANGe Command (RANG) . . . . . . . . . . . . . . . . . . . 5 58 4.1. FEAT Command Response for RANG Command . . . . . . . . . . 7 59 4.2. User-PI usage of RANG . . . . . . . . . . . . . . . . . . 7 60 4.3. RANG Command Errors . . . . . . . . . . . . . . . . . . . 8 61 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 62 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 63 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 64 7.1. Normative References . . . . . . . . . . . . . . . . . . . 9 65 7.2. Informative References . . . . . . . . . . . . . . . . . . 9 66 Appendix A. Acknowledgements and Contributors . . . . . . . . . . 9 67 Appendix B. Document History . . . . . . . . . . . . . . . . . . 10 68 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10 70 1. Introduction 72 The File Transfer Protocol offers REST [RFC3659], to designate a 73 starting point for a transfer, but does not currently offer any 74 method to specify an end point. This document specifies a new FTP 75 RANG command to be used by clients to designate a start and end point 76 for STREAM mode transfers with RETR. 78 The current alternatives, without being able to specify an end point, 79 are to issue an ABOR command or close the data connection. 81 HTTP offers similar functionality with the Range: header in Section 82 14.35 of [RFC2616], where a specific byte range can optionally be 83 requested. 85 [[ Discussion of this draft should take place on the FTPEXT2 Working 86 Group mailing list, although this draft is not a WG item: 87 ftpext@ietf.org. ]] 89 2. Document Conventions 91 This specification describes conformance of File Transfer Protocol 92 Extension for RANG, and end point in a byte range. 94 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 95 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 96 document are to be interpreted as described in BCP 14, [RFC2119], as 97 scoped to those conformance targets. 99 This document also uses notation defined in STD 9, [RFC0959]. In 100 particular, the terms or commands "reply", "user", "file", "FTP 101 commands", "user-PI" (user protocol interpreter), "server-FTP 102 process", "server-PI", "mode", "Image type", "Stream transfer mode", 103 "type", "STOR", "RETR", and "ASCII", are all used here as defined 104 there. The command "REST" is used as defined in Section 5 of 105 [RFC3659]. 107 In the examples of FTP dialogs presented in this document, lines that 108 begin "C> " were sent over the control connection from the user-PI to 109 the server-PI, and lines that begin "S> " were sent over the control 110 connection from the server-PI to the user-PI. In all cases, the 111 prefixes shown above, including the one space, have been added for 112 the purposes of this document, and are not a part of the data 113 exchanged between client and server. 115 Syntax required is defined using the Augmented BNF defined in 116 [RFC5234]. 118 2.1. Basic Tokens 120 This document imports the core definitions given in Appendix B of 121 [RFC5234]. There definitions will be found for basic ABNF elements 122 like ALPHA, DIGIT, SP, etc. To that, the following term is added for 123 use in this document. 125 TCHAR = VCHAR / SP / HTAB ; visible plus white space 127 The VCHAR (from [RFC5234]) and TCHAR rules give basic character types 128 from varying sub-sets of the ASCII character set for use in various 129 commands and responses. 131 Note that in ABNF, string literals are case insensitive. That 132 convention is preserved in this document, and implies that FTP 133 commands and parameters that are added by this specification have 134 values that can be represented in any case. That is, "RANG" is the 135 same as "rang", "Rang", "RaNg", etc., and "ftp.example.com" is the 136 same as "Ftp.Example.Com", "fTp.eXample.cOm", etc. 138 2.2. Server Replies 140 Section 4.2 of [RFC0959] defines the format and meaning of replies by 141 the server-PI to FTP commands from the user-PI. Those reply 142 conventions are used here without change. 144 error-response = error-code SP *TCHAR CRLF 145 error-code = ("4" / "5") 2DIGIT 147 Implementers should note that the ABNF syntax (which was not used in 148 [RFC0959]) used in this document, and other FTP related documents, 149 sometimes shows replies using the one line format. Unless otherwise 150 explicitly stated, that is not intended to imply that multi-line 151 responses are not permitted. Implementers should assume that, unless 152 stated to the contrary, any reply to any FTP command (including QUIT) 153 can be of the multi-line format described in [RFC0959]. 155 Throughout this document, replies will be identified by the three 156 digit code that is their first element. Thus the term "500 reply" 157 means a reply from the server-PI using the three digit code "500". 159 3. Byte Ranges in STREAM Mode 161 In STREAM mode, the data connection contains just a stream of 162 unformatted octets of data. Explicit restart markers thus cannot be 163 inserted into the data stream, they would be indistinguishable from 164 data. For this reason, the FTP specification [RFC0959] did not 165 provide the ability to do restarts in stream mode. However, there is 166 not really a need to have explicit restart markers in this case, as 167 restart markers can be implied by the octet offset into the data 168 stream. 170 Because the data stream defines the file in STREAM mode, a different 171 data stream would represent a different file. Thus, an offset will 172 always represent the same position within a file. On the other hand, 173 in other modes than STREAM, the same file can be transferred using 174 quite different octet sequences and yet be reconstructed into the one 175 identical file. Thus an offset into the data stream in transfer 176 modes other than STREAM would not give an unambiguous restart or end 177 point. 179 If the data representation TYPE is IMAGE and the STRUcture is File, 180 for many systems the file will be stored exactly in the same format 181 as it is sent across the data connection. It is then usually very 182 easy for the receiver to determine how much data was previously 183 received, and notify the sender of the offset where the transfer 184 should be restarted. In other representation types and structures 185 more effort will be required, but it remains always possible to 186 determine the offset with finite, but perhaps non-negligible, effort. 187 In the worst case, an FTP process may need to open a data connection 188 to itself, set the appropriate transfer type and structure, and 189 actually transmit the file, counting the transmitted octets. 191 If the user-FTP process is intending to restart a retrieve, it will 192 directly calculate the restart marker and send that information in 193 the RESTart command. However, if the user-FTP process is intending 194 to restart sending the file, it needs to be able to determine how 195 much data was previously sent, and correctly received and saved. The 196 purpose of the SIZE command, as documented in [RFC3659], is to get 197 this information. 199 4. The RANGe Command (RANG) 201 A new command "RANG" is added to the FTP command set to allow the 202 client to specify both an start point byte range and an end point 203 byte range of a file from a server-FTP process. 205 The syntax for the RANG command when the current transfer mode is 206 STREAM is: 208 range-command = "RANG" SP start-point SP end-point CRLF 209 start-point = 1*DIGIT 210 end-point = 1*DIGIT 212 [NOTE: end-point is inclusive.] 214 start-point gives the number of octets of the immediately-following 215 transfer to not actually send, effectively causing the transmission 216 to be started at a later point. A value of zero effectively causes 217 the transmission to be started at first byte. end-point gives the 218 number of octets, counted from the beginning of the file, of the 219 immediately-following transfer to stop sending at, effectively 220 causing the transmission to be ended. (That is, the end point is 221 relative to the start of the file and not relative to the start 222 point). The server-PI will response to the RANG command with a 350 223 reply, indicating that RANG parameters has been saved, and that 224 another command, which should be RETR, should then follow to complete 225 the ranged request. 227 range-response = range-ok / error-response 228 range-ok = "350" SP *TCHAR CRLF 230 The RANG command is intended to get partial data of a file. When the 231 RANG command is used with RETR, client bears the responsibility of 232 merging the retrieved data with partially retrieved file. It may 233 choose to use the data obtained other than to complete an earlier 234 transfer, or to re-retrieve data that had been retrieved before. 236 The RANG command must be the last command issued before the data 237 transfer command that is to cause a partial data transfer. The 238 effect of issuing a RANG command at any other time is undefined. The 239 server-PI may react to a badly positioned RANG command by issuing an 240 error response to the following command, not being a restartable data 241 transfer command, or it may save the start-point and/or end-point 242 byte range value and apply it to the next data transfer command, or 243 it may silently ignore the inappropriate restart attempt. Because of 244 this, a user-PI that has issued a RANG command, but that has not 245 successfully transmitted the following data transfer command for any 246 reason, should send another RANG command before the next data 247 transfer command. If that transfer is not to be restarted, then 248 "REST 0" should be issued. 250 An error response will follow a RANG command only when the server 251 does not implement the command, or when command syntax is invalid. 252 Any other errors, including such problems as start-point and/or end- 253 point byte range out of range, should be reported when the following 254 transfer command is issued. Such errors will cause that transfer 255 request to be rejected with an error indicating the invalid restart 256 attempt. 258 4.1. FEAT Command Response for RANG Command 260 When replying to the FEAT command [RFC2389], a server-FTP process 261 that supports the RANG command, as specified here, MUST include, a 262 line containing exactly the string "RANG STREAM". This string is 263 case insensitive, and MAY be sent in any mixture of upper or lower 264 case, however it SHOULD be sent in upper case. That is, the response 265 SHOULD be: 267 C> FEAT 268 S> 211-Extensions supported: 269 S> ... 270 S> RANG STREAM 271 S> ... 272 S> 211 END 274 The ellipses indicate place holders where other features may be 275 included, and are not required. The one-space indentation of the 276 feature lines is mandatory [RFC2389]. 278 range-feat = SP "RANG" SP "STREAM" 280 4.2. User-PI usage of RANG 282 The user-PI issues the FEAT command to query the server-PI if it 283 supports the RANG command. In this example, the server-PI also 284 supports REST. 286 C> FEAT 287 S> 211-Extensions supported: 288 S> ... 289 S> REST STREAM 290 S> RANG STREAM 291 S> ... 292 S> 211 END 294 Assume that the transfer of a largish file has previously been 295 interrupted after 802816 octets had been received, that the tranfer 296 should stop at octet 1000000 of the file, that the previous transfer 297 was with TYPE=I, and that it has been verified that the file on the 298 server has not since changed. 300 C> TYPE I 301 S> 200 Type set to I. 302 C> PORT 127,0,0,1,15,107 303 S> 200 PORT command successful. 304 C> RANG 802816 1000000 305 S> 350 Restarting at 802816. End Byte range at 1000000. Send RETRIEVE 306 C> RETR cap60.pl198.tar 307 S> 150 Opening BINARY mode data connection 308 [...] 309 S> 226 Transfer complete. 311 In the above example, data is sent from offset 802816 to, and 312 including, offset 1000000. 314 4.3. RANG Command Errors 316 The server-PI SHOULD reply with a 500 reply if the RANG command is 317 unrecognized or unimplemented. 319 The server-PI SHOULD reply with a 550 reply if the RANG command is 320 used on a file that can not be found. 322 The server-PI SHOULD reply with a 551 reply if the server-PI is 323 unable to deliver the file with TYPE I and MODE S. 325 The server-PI SHOULD reply with a 552 reply if the user is not 326 allowed to use the RANG command. 328 The server-PI SHOULD reply with a 553 reply if the user requests the 329 RANG of a directory, which is not allowed. 331 The server-PI SHOULD reply with a 5yz reply if the specified end 332 point is larger than the actual file or the end point is before the 333 start point. 335 5. IANA Considerations 337 This new command is added to the "FTP Commands and Extensions" 338 registry created by [RFC5797]. 340 Command Name: RANG 342 Description: End point byte range (for STREAM mode). 344 FEAT String: RANG 346 Command Type: Service execution/parameter setting 347 Conformance Requirements: Optional 349 Reference: This specification 351 6. Security Considerations 353 This memo does not directly concern security. It is not believed 354 that any of the mechanisms documented here impact in any particular 355 way upon the security of FTP. 357 7. References 359 7.1. Normative References 361 [RFC0959] Postel, J. and J. Reynolds, "File Transfer Protocol", 362 STD 9, RFC 0959, October 1985. 364 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 365 Requirement Levels", BCP 14, RFC 2119, March 1997. 367 [RFC2389] Hethmon, P. and R. Elz, "Feature negotiation mechanism for 368 the File Transfer Protocol", RFC 2389, August 1998. 370 [RFC3659] Hethmon, P., "Extensions to FTP", RFC 3659, March 2007. 372 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 373 Specifications: ABNF", STD 68, RFC 5234, January 2008. 375 7.2. Informative References 377 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 378 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 379 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 381 [RFC5797] Klensin, J. and A. Hoenes, "FTP Command and Extension 382 Registry", RFC 5797, March 2010. 384 Appendix A. Acknowledgements and Contributors 386 Thanks to ... 388 Portions of [RFC3659] were wholly reused in this document. 390 Appendix B. Document History 392 [[ to be removed by the RFC editor before publication as an RFC. ]] 394 Known issues concerning this draft: 395 o Expand current alternatives (ABOR, close data connection) and why 396 they are not optimal. 398 draft-bryan-ftp-range-00 : December 13, 2010. 399 o Initial draft. 401 Authors' Addresses 403 Anthony Bryan 404 Pompano Beach, FL 405 USA 407 Email: anthonybryan@gmail.com 408 URI: http://www.metalinker.org 410 Tatsuhiro Tsujikawa 411 Shiga 412 Japan 414 Email: tatsuhiro.t@gmail.com 415 URI: http://aria2.sourceforge.net 417 Daniel Stenberg 419 Email: daniel@haxx.se 420 URI: http://www.haxx.se/