Tech-invite3GPPspaceIETF RFCsSIP
93929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 3659

Extensions to FTP

Pages: 61
Proposed Standard
Errata
Updates:  0959
Part 1 of 3 – Pages 1 to 17
None   None   Next

Top   ToC   RFC3659 - Page 1
Network Working Group                                         P. Hethmon
Request for Comments: 3659                              Hethmon Software
Updates: 959                                                  March 2007
Category: Standards Track


                           Extensions to FTP

Status of This Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The IETF Trust (2007).

Abstract

This document specifies new FTP commands to obtain listings of remote directories in a defined format, and to permit restarts of interrupted data transfers in STREAM mode. It allows character sets other than US-ASCII, and also defines an optional virtual file storage structure.
Top   ToC   RFC3659 - Page 2

Table of Contents

1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Document Conventions . . . . . . . . . . . . . . . . . . . . . 3 2.1. Basic Tokens . . . . . . . . . . . . . . . . . . . . . . 4 2.2. Pathnames. . . . . . . . . . . . . . . . . . . . . . . . 4 2.3. Times. . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.4. Server Replies . . . . . . . . . . . . . . . . . . . . . 7 2.5. Interpreting Examples. . . . . . . . . . . . . . . . . . 8 3. File Modification Time (MDTM). . . . . . . . . . . . . . . . . 8 3.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.2. Error Responses. . . . . . . . . . . . . . . . . . . . . 9 3.3. FEAT Response for MDTM . . . . . . . . . . . . . . . . . 10 3.4. MDTM Examples. . . . . . . . . . . . . . . . . . . . . . 10 4. File SIZE. . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.2. Error Responses. . . . . . . . . . . . . . . . . . . . . 12 4.3. FEAT Response for SIZE . . . . . . . . . . . . . . . . . 12 4.4. Size Examples. . . . . . . . . . . . . . . . . . . . . . 12 5. Restart of Interrupted Transfer (REST) . . . . . . . . . . . . 13 5.1. Restarting in STREAM Mode. . . . . . . . . . . . . . . . 14 5.2. Error Recovery and Restart . . . . . . . . . . . . . . . 14 5.3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 15 5.4. FEAT Response for REST . . . . . . . . . . . . . . . . . 16 5.5. REST Example . . . . . . . . . . . . . . . . . . . . . . 17 6. A Trivial Virtual File Store (TVFS). . . . . . . . . . . . . . 17 6.1. TVFS File Names. . . . . . . . . . . . . . . . . . . . . 18 6.2. TVFS Pathnames . . . . . . . . . . . . . . . . . . . . . 18 6.3. FEAT Response for TVFS . . . . . . . . . . . . . . . . . 20 6.4. OPTS for TVFS. . . . . . . . . . . . . . . . . . . . . . 21 6.5. TVFS Examples. . . . . . . . . . . . . . . . . . . . . . 21 7. Listings for Machine Processing (MLST and MLSD). . . . . . . . 23 7.1. Format of MLSx Requests. . . . . . . . . . . . . . . . . 23 7.2. Format of MLSx Response. . . . . . . . . . . . . . . . . 24 7.3. File Name Encoding . . . . . . . . . . . . . . . . . . . 26 7.4. Format of Facts. . . . . . . . . . . . . . . . . . . . . 28 7.5. Standard Facts . . . . . . . . . . . . . . . . . . . . . 28 7.6. System Dependent and Local Facts . . . . . . . . . . . . 36 7.7. MLSx Examples. . . . . . . . . . . . . . . . . . . . . . 37 7.8. FEAT Response for MLSx . . . . . . . . . . . . . . . . . 49 7.9. OPTS Parameters for MLST . . . . . . . . . . . . . . . . 51 8. Impact on Other FTP Commands . . . . . . . . . . . . . . . . . 54 9. Character Sets and Internationalization. . . . . . . . . . . . 55 10. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 55 10.1. The OS Specific Fact Registry. . . . . . . . . . . . . . 56 10.2. The OS Specific Filetype Registry. . . . . . . . . . . . 56
Top   ToC   RFC3659 - Page 3
   11. Security Considerations. . . . . . . . . . . . . . . . . . . . 57
   12. Normative References . . . . . . . . . . . . . . . . . . . . . 58
   Acknowledgments. . . . . . . . . . . . . . . . . . . . . . . . . . 59

1. Introduction

This document updates the File Transfer Protocol (FTP) [3]. Four new commands are added: "SIZE", "MDTM", "MLST", and "MLSD". The existing command "REST" is modified. Of those, the "SIZE" and "MDTM" commands, and the modifications to "REST" have been in wide use for many years. The others are new. These commands allow a client to restart an interrupted transfer in transfer modes not previously supported in any documented way, and to obtain a directory listing in a machine friendly, predictable, format. An optional structure for the server's file store (NVFS) is also defined, allowing servers that support such a structure to convey that information to clients in a standard way, thus allowing clients more certainty in constructing and interpreting pathnames.

2. Document Conventions

This document makes use of the document conventions defined in BCP 14, RFC 2119 [4]. That provides the interpretation of capitalized imperative words like MUST, SHOULD, etc. This document also uses notation defined in STD 9, RFC 959 [3]. In particular, the terms "reply", "user", "NVFS" (Network Virtual File System), "file", "pathname", "FTP commands", "DTP" (data transfer process), "user-FTP process", "user-PI" (user protocol interpreter), "user-DTP", "server-FTP process", "server-PI", "server-DTP", "mode", "type", "NVT" (Network Virtual Terminal), "control connection", "data connection", and "ASCII", are all used here as defined there. Syntax required is defined using the Augmented BNF defined in [5]. Some general ABNF definitions that are required throughout the document will be defined later in this section. At first reading, it may be wise to simply recall that these definitions exist here, and skip to the next section.
Top   ToC   RFC3659 - Page 4

2.1. Basic Tokens

This document imports the core ABNF definitions given in Appendix A of [5]. There definitions will be found for basic ABNF elements like ALPHA, DIGIT, SP, etc. The following terms are added for use in this document. TCHAR = VCHAR / SP / HTAB ; visible plus white space RCHAR = ALPHA / DIGIT / "," / "." / ":" / "!" / "@" / "#" / "$" / "%" / "^" / "&" / "(" / ")" / "-" / "_" / "+" / "?" / "/" / "\" / "'" / DQUOTE ; <"> -- double quote character (%x22) SCHAR = RCHAR / "=" ; The VCHAR (from [5]), RCHAR, SCHAR, and TCHAR types give basic character types from varying sub-sets of the ASCII character set for use in various commands and responses. token = 1*RCHAR A "token" is a string whose precise meaning depends upon the context in which it is used. In some cases it will be a value from a set of possible values maintained elsewhere. In others it might be a string invented by one party to an FTP conversation from whatever sources it finds relevant. Note that in ABNF, string literals are case insensitive. That convention is preserved in this document, and implies that FTP commands added by this specification have names that can be represented in any case. That is, "MDTM" is the same as "mdtm", "Mdtm" and "MdTm" etc. However note that ALPHA, in particular, is case sensitive. That implies that a "token" is a case sensitive value. That implication is correct, except where explicitly stated to the contrary in this document, or in some other specification that defines the values this document specifies be used in a particular context.

2.2. Pathnames

Various FTP commands take pathnames as arguments, or return pathnames in responses. When the MLST command is supported, as indicated in the response to the FEAT command [6], pathnames are to be transferred in one of the following two formats.
Top   ToC   RFC3659 - Page 5
      pathname       = utf-8-name / raw
      utf-8-name     = <a UTF-8 encoded Unicode string>
      raw            = <any string that is not a valid UTF-8 encoding>

   Which format is used is at the option of the user-PI or server-PI
   sending the pathname.  UTF-8 encodings [2] contain enough internal
   structure that it is always, in practice, possible to determine
   whether a UTF-8 or raw encoding has been used, in those cases where
   it matters.  While it is useful for the user-PI to be able to
   correctly display a pathname received from the server-PI to the user,
   it is far more important for the user-PI to be able to retain and
   retransmit the identical pathname when required.  Implementations are
   advised against converting a UTF-8 pathname to a local charset that
   isn't capable of representing the full Unicode character repertoire,
   and then attempting to invert the charset translation later.  Note
   that ASCII is a subset of UTF-8.  See also [1].

   Unless otherwise specified, the pathname is terminated by the CRLF
   that terminates the FTP command, or by the CRLF that ends a reply.
   Any trailing spaces preceding that CRLF form part of the name.
   Exactly one space will precede the pathname and serve as a separator
   from the preceding syntax element.  Any additional spaces form part
   of the pathname.  See [7] for a fuller explanation of the character
   encoding issues.  All implementations supporting MLST MUST support
   [7].

   Note: for pathnames transferred over a data connection, there is no
   way to represent a pathname containing the characters CR and LF in
   sequence, and distinguish that from the end of line indication.
   Hence, pathnames containing the CRLF pair of characters cannot be
   transmitted over a data connection.  Data connections only contain
   file names transmitted from server-FTP to user-FTP as the result of
   one of the directory listing commands.  Files with names containing
   the CRLF sequence must either have that sequence converted to some
   other form, such that the other form can be recognised and be
   correctly converted back to CRLF, or be omitted from the listing.

   Implementations should also beware that the FTP control connection
   uses Telnet NVT conventions [8], and that the Telnet IAC character,
   if part of a pathname sent over the control connection, MUST be
   correctly escaped as defined by the Telnet protocol.

   NVT also distinguishes between CR, LF, and the end of line CRLF, and
   so would permit pathnames containing the pair of characters CR and LF
   to be correctly transmitted.  However, because such a sequence cannot
   be transmitted over a data connection (as part of the result of a
   LIST, NLST, or MLSD command), such pathnames are best avoided.
Top   ToC   RFC3659 - Page 6
   Implementors should also be aware that, although Telnet NVT
   conventions are used over the control connections, Telnet option
   negotiation MUST NOT be attempted.  See section 4.1.2.12 of [9].

2.2.1. Pathname Syntax

Except where TVFS is supported (see section 6), this specification imposes no syntax upon pathnames. Nor does it restrict the character set from which pathnames are created. This does not imply that the NVFS is required to make sense of all possible pathnames. Server-PIs may restrict the syntax of valid pathnames in their NVFS in any manner appropriate to their implementation or underlying file system. Similarly, a server-PI may parse the pathname and assign meaning to the components detected.

2.2.2. Wildcarding

For the commands defined in this specification, all pathnames are to be treated literally. That is, for a pathname given as a parameter to a command, the file whose name is identical to the pathname given is implied. No characters from the pathname may be treated as special or "magic", thus no pattern matching (other than for exact equality) between the pathname given and the files present in the NVFS of the server-FTP is permitted. Clients that desire some form of pattern matching functionality must obtain a listing of the relevant directory, or directories, and implement their own file name selection procedures.

2.3. Times

The syntax of a time value is: time-val = 14DIGIT [ "." 1*DIGIT ] The leading, mandatory, fourteen digits are to be interpreted as, in order from the leftmost, four digits giving the year, with a range of 1000--9999, two digits giving the month of the year, with a range of 01--12, two digits giving the day of the month, with a range of 01--31, two digits giving the hour of the day, with a range of 00--23, two digits giving minutes past the hour, with a range of 00--59, and finally, two digits giving seconds past the minute, with a range of 00--60 (with 60 being used only at a leap second). Years in the tenth century, and earlier, cannot be expressed. This is not considered a serious defect of the protocol.
Top   ToC   RFC3659 - Page 7
   The optional digits, which are preceded by a period, give decimal
   fractions of a second.  These may be given to whatever precision is
   appropriate to the circumstance, however implementations MUST NOT add
   precision to time-vals where that precision does not exist in the
   underlying value being transmitted.

   Symbolically, a time-val may be viewed as

      YYYYMMDDHHMMSS.sss

   The "." and subsequent digits ("sss") are optional.  However the "."
   MUST NOT appear unless at least one following digit also appears.

   Time values are always represented in UTC (GMT), and in the Gregorian
   calendar regardless of what calendar may have been in use at the date
   and time indicated at the location of the server-PI.

   The technical differences among GMT, TAI, UTC, UT1, UT2, etc., are
   not considered here.  A server-FTP process should always use the same
   time reference, so the times it returns will be consistent.  Clients
   are not expected to be time synchronized with the server, so the
   possible difference in times that might be reported by the different
   time standards is not considered important.

2.4. Server Replies

Section 4.2 of [3] defines the format and meaning of replies by the server-PI to FTP commands from the user-PI. Those reply conventions are used here without change. error-response = error-code SP *TCHAR CRLF error-code = ("4" / "5") 2DIGIT Implementors should note that the ABNF syntax used in this document and in other FTP related documents (but not used in [3]), sometimes shows replies using the one-line format. Unless otherwise explicitly stated, that is not intended to imply that multi-line responses are not permitted. Implementors should assume that, unless stated to the contrary, any reply to any FTP command (including QUIT) may use the multi-line format described in [3]. Throughout this document, replies will be identified by the three digit code that is their first element. Thus the term "500 reply" means a reply from the server-PI using the three digit code "500".
Top   ToC   RFC3659 - Page 8

2.5. Interpreting Examples

In the examples of FTP dialogs presented in this document, lines that begin "C> " were sent over the control connection from the user-PI to the server-PI, lines that begin "S> " were sent over the control connection from the server-PI to the user-PI, and each sequence of lines that begin "D> " was sent from the server-PI to the user-PI over a data connection created just to send those lines and closed immediately after. No examples here show data transferred over a data connection from the client to the server. In all cases, the prefixes shown above, including the one space, have been added for the purposes of this document, and are not a part of the data exchanged between client and server.

3. File Modification Time (MDTM)

The FTP command, MODIFICATION TIME (MDTM), can be used to determine when a file in the server NVFS was last modified. This command has existed in many FTP servers for many years, as an adjunct to the REST command for STREAM mode, thus is widely available. However, where supported, the "modify" fact that can be provided in the result from the new MLST command is recommended as a superior alternative. When attempting to restart a RETRieve, the user-FTP can use the MDTM command or the "modify" fact to check if the modification time of the source file is more recent than the modification time of the partially transferred file. If it is, then most likely the source file has changed, and it would be unsafe to restart the previously incomplete file transfer. Because the user- and server-FTPs' clocks are not necessarily synchronised, user-FTPs intending to use this method should usually obtain the modification time of the file from the server before the initial RETRieval, and compare that with the modification time before a RESTart. If they differ, the files may have changed, and RESTart would be inadvisable. Where this is not possible, the user-FTP should make sure to allow for possible clock skew when comparing times. When attempting to restart a STORe, the User FTP can use the MDTM command to discover the modification time of the partially transferred file. If it is older than the modification time of the file that is about to be STORed, then most likely the source file has changed, and it would be unsafe to restart the file transfer.
Top   ToC   RFC3659 - Page 9
   Note that using MLST (described below), where available, can provide
   this information and much more, thus giving an even better indication
   that a file has changed and that restarting a transfer would not give
   valid results.

   Note that this is applicable to any RESTart attempt, regardless of
   the mode of the file transfer.

3.1. Syntax

The syntax for the MDTM command is: mdtm = "MdTm" SP pathname CRLF As with all FTP commands, the "MDTM" command label is interpreted in a case-insensitive manner. The "pathname" specifies an object in the NVFS that may be the object of a RETR command. Attempts to query the modification time of files that exist but are unable to be retrieved may generate an error- response, or can result in a positive response carrying a time-val with an unspecified value, the choice being made by the server-PI. The server-PI will respond to the MDTM command with a 213 reply giving the last modification time of the file whose pathname was supplied, or a 550 reply if the file does not exist, the modification time is unavailable, or some other error has occurred. mdtm-response = "213" SP time-val CRLF / error-response Note that when the 213 response is issued, that is, when there is no error, the format MUST be exactly as specified. Multi-line responses are not permitted.

3.2. Error Responses

Where the command is correctly parsed but the modification time is not available, either because the pathname identifies no existing entity or because the information is not available for the entity named, then a 550 reply should be sent. Where the command cannot be correctly parsed, a 500 or 501 reply should be sent, as specified in [3]. Various 4xy replies are also possible in appropriate circumstances.
Top   ToC   RFC3659 - Page 10

3.3. FEAT Response for MDTM

When replying to the FEAT command [6], a server-FTP process that supports the MDTM command MUST include a line containing the single word "MDTM". This MAY be sent in upper or lower case or a mixture of both (it is case insensitive), but SHOULD be transmitted in upper case only. That is, the response SHOULD be: C> Feat S> 211- <any descriptive text> S> ... S> MDTM S> ... S> 211 End The ellipses indicate place holders where other features may be included, but are not required. The one-space indentation of the feature lines is mandatory [6].

3.4. MDTM Examples

If we assume the existence of three files, A B and C, a directory D, two files with names that end with the string "ile6", and no other files at all, then the MDTM command may behave as indicated. The "C>" lines are commands from user-PI to server-PI, the "S>" lines are server-PI replies. C> MDTM A S> 213 19980615100045.014 C> MDTM B S> 213 19980615100045.014 C> MDTM C S> 213 19980705132316 C> MDTM D S> 550 D is not retrievable C> MDTM E S> 550 No file named "E" C> mdtm file6 S> 213 19990929003355 C> MdTm 19990929043300 File6 S> 213 19991005213102 C> MdTm 19990929043300 file6 S> 550 19990929043300 file6: No such file or directory. From that we can conclude that both A and B were last modified at the same time (to the nearest millisecond), and that C was modified 20 days and several hours later.
Top   ToC   RFC3659 - Page 11
   The times are in GMT, so file A was modified on the 15th of June,
   1998, at approximately 11am in London (summer time was then in
   effect), or perhaps at 8pm in Melbourne, Australia, or at 6am in New
   York.  All of those represent the same absolute time, of course.  The
   location where the file was modified, and consequently the local wall
   clock time at that location, is not available.

   There is no file named "E" in the current directory, but there are
   files named both "file6" and "19990929043300 File6".  The
   modification times of those files were obtained.  There is no file
   named "19990929043300 file6".

4. File SIZE

The FTP command, SIZE OF FILE (SIZE), is used to obtain the transfer size of a file from the server-FTP process. This is the exact number of octets (8 bit bytes) that would be transmitted over the data connection should that file be transmitted. This value will change depending on the current STRUcture, MODE, and TYPE of the data connection or of a data connection that would be created were one created now. Thus, the result of the SIZE command is dependent on the currently established STRU, MODE, and TYPE parameters. The SIZE command returns how many octets would be transferred if the file were to be transferred using the current transfer structure, mode, and type. This command is normally used in conjunction with the RESTART (REST) command when STORing a file to a remote server in STREAM mode, to determine the restart point. The server-PI might need to read the partially transferred file, do any appropriate conversion, and count the number of octets that would be generated when sending the file in order to correctly respond to this command. Estimates of the file transfer size MUST NOT be returned; only precise information is acceptable.

4.1. Syntax

The syntax of the SIZE command is: size = "Size" SP pathname CRLF The server-PI will respond to the SIZE command with a 213 reply giving the transfer size of the file whose pathname was supplied, or an error response if the file does not exist, the size is unavailable, or some other error has occurred. The value returned is in a format suitable for use with the RESTART (REST) command for mode STREAM, provided the transfer mode and type are not altered.
Top   ToC   RFC3659 - Page 12
      size-response = "213" SP 1*DIGIT CRLF /
                      error-response

   Note that when the 213 response is issued, that is, when there is no
   error, the format MUST be exactly as specified.  Multi-line responses
   are not permitted.

4.2. Error Responses

Where the command is correctly parsed but the size is not available, perhaps because the pathname identifies no existing entity or because the entity named cannot be transferred in the current MODE and TYPE (or at all), then a 550 reply should be sent. Where the command cannot be correctly parsed, a 500 or 501 reply should be sent, as specified in [3]. The presence of the 550 error response to a SIZE command MUST NOT be taken by the client as an indication that the file cannot be transferred in the current MODE and TYPE. A server may generate this error for other reasons -- for instance if the processing overhead is considered too great. Various 4xy replies are also possible in appropriate circumstances.

4.3. FEAT Response for SIZE

When replying to the FEAT command [6], a server-FTP process that supports the SIZE command MUST include a line containing the single word "SIZE". This word is case insensitive, and MAY be sent in any mixture of upper or lower case, however it SHOULD be sent in upper case. That is, the response SHOULD be: C> FEAT S> 211- <any descriptive text> S> ... S> SIZE S> ... S> 211 END The ellipses indicate place holders where other features may be included, and are not required. The one-space indentation of the feature lines is mandatory [6].

4.4. Size Examples

Consider a text file "Example" stored on a Unix(TM) server where each end of line is represented by a single octet. Assume the file contains 112 lines, and 1830 octets total. Then the SIZE command would produce:
Top   ToC   RFC3659 - Page 13
      C> TYPE I
      S> 200 Type set to I.
      C> size Example
      S> 213 1830
      C> TYPE A
      S> 200 Type set to A.
      C> Size Example
      S> 213 1942

   Notice that with TYPE=A the SIZE command reports an extra 112 octets.
   Those are the extra octets that need to be inserted, one at the end
   of each line, to provide correct end-of-line semantics for a transfer
   using TYPE=A.  Other systems might need to make other changes to the
   transfer format of files when converting between TYPEs and MODEs.
   The SIZE command takes all of that into account.

   Since calculating the size of a file with this degree of precision
   may take considerable effort on the part of the server-PI, user-PIs
   should not used this command unless this precision is essential (such
   as when about to restart an interrupted transfer).  For other uses,
   the "Size" fact of the MLST command (see section 7.5.7) ought be
   requested.

5. Restart of Interrupted Transfer (REST)

To avoid having to resend the entire file if the file is only partially transferred, both sides need some way to agree on where in the data stream to restart the data transfer. The FTP specification [3] includes three modes of data transfer, STREAM, Block, and Compressed. In Block and Compressed modes, the data stream that is transferred over the data connection is formatted, allowing the embedding of restart markers into the stream. The sending DTP can include a restart marker with whatever information it needs to be able to restart a file transfer at that point. The receiving DTP can keep a list of these restart markers, and correlate them with how the file is being saved. To restart the file transfer, the receiver just sends back that last restart marker, and both sides know how to resume the data transfer. Note that there are some flaws in the description of the restart mechanism in STD 9, RFC 959 [3]. See section 4.1.3.4 of RFC 1123 [9] for the corrections.
Top   ToC   RFC3659 - Page 14

5.1. Restarting in STREAM Mode

In STREAM mode, the data connection contains just a stream of unformatted octets of data. Explicit restart markers thus cannot be inserted into the data stream, they would be indistinguishable from data. For this reason, the FTP specification [3] did not provide the ability to do restarts in stream mode. However, there is not really a need to have explicit restart markers in this case, as restart markers can be implied by the octet offset into the data stream. Because the data stream defines the file in STREAM mode, a different data stream would represent a different file. Thus, an offset will always represent the same position within a file. On the other hand, in other modes than STREAM, the same file can be transferred using quite different octet sequences and yet be reconstructed into the one identical file. Thus an offset into the data stream in transfer modes other than STREAM would not give an unambiguous restart point. If the data representation TYPE is IMAGE and the STRUcture is File, for many systems the file will be stored exactly in the same format as it is sent across the data connection. It is then usually very easy for the receiver to determine how much data was previously received, and notify the sender of the offset where the transfer should be restarted. In other representation types and structures more effort will be required, but it remains always possible to determine the offset with finite, but perhaps non-negligible, effort. In the worst case, an FTP process may need to open a data connection to itself, set the appropriate transfer type and structure, and actually transmit the file, counting the transmitted octets. If the user-FTP process is intending to restart a retrieve, it will directly calculate the restart marker and send that information in the RESTart command. However, if the user-FTP process is intending to restart sending the file, it needs to be able to determine how much data was previously sent, and correctly received and saved. A new FTP command is needed to get this information. This is the purpose of the SIZE command, as documented in section 4.

5.2. Error Recovery and Restart

STREAM mode transfers with FILE STRUcture may be restarted even though no restart marker has been transferred in addition to the data itself. This is done by using the SIZE command, if needed, in combination with the RESTART (REST) command, and one of the standard file transfer commands. When using TYPE ASCII or IMAGE, the SIZE command will return the number of octets that would actually be transferred if the file were
Top   ToC   RFC3659 - Page 15
   to be sent between the two systems, i.e., with type IMAGE, the SIZE
   normally would be the number of octets in the file.  With type ASCII,
   the SIZE would be the number of octets in the file including any
   modifications required to satisfy the TYPE ASCII CR-LF end-of-line
   convention.

5.3. Syntax

The syntax for the REST command when the current transfer mode is STREAM is: rest = "Rest" SP 1*DIGIT CRLF The numeric value gives the number of octets of the immediately- following transfer to not actually send, effectively causing the transmission to be restarted at a later point. A value of zero effectively disables restart, causing the entire file to be transmitted. The server-PI will respond to the REST command with a 350 reply, indicating that the REST parameter has been saved, and that another command, which should be either RETR or STOR, should then follow to complete the restart. rest-response = "350" SP *TCHAR CRLF / error-response Server-FTP processes may permit transfer commands other than RETR and STOR, such as APPE and STOU, to complete a restart; however, this is not recommended. STOU (store unique) is undefined in this usage, as storing the remainder of a file into a unique file name is rarely going to be useful. If APPE (append) is permitted, it MUST act identically to STOR when a restart marker has been set. That is, in both cases, octets from the data connection are placed into the file at the location indicated by the restart marker value. The REST command is intended to complete a failed transfer. Use with RETR is comparatively well defined in all cases, as the client bears the responsibility of merging the retrieved data with the partially retrieved file. It may choose to use the data obtained other than to complete an earlier transfer, or to re-retrieve data that had been retrieved before. With STOR, however, the server must insert the data into the file named. The results are undefined if a client uses REST to do other than restart to complete a transfer of a file that had previously failed to completely transfer. In particular, if the restart marker set with a REST command is not at the end of the data currently stored at the server, as reported by the server, or if insufficient data are provided in a STOR that follows a REST to extend the destination file to at least its previous size, then the effects are undefined.
Top   ToC   RFC3659 - Page 16
   The REST command must be the last command issued before the data
   transfer command that is to cause a restarted, rather than a
   complete, file transfer.  The effect of issuing a REST command at any
   other time is undefined.  The server-PI may react to a badly
   positioned REST command by issuing an error response to the following
   command, not being a restartable data transfer command, or it may
   save the restart value and apply it to the next data transfer
   command, or it may silently ignore the inappropriate restart attempt.
   Because of this, a user-PI that has issued a REST command, but that
   has not successfully transmitted the following data transfer command
   for any reason, should send another REST command before the next data
   transfer command.  If that transfer is not to be restarted, then
   "REST 0" should be issued.

   An error response will follow a REST command only when the server
   does not implement the command, or when the restart marker value is
   syntactically invalid for the current transfer mode (e.g., in STREAM
   mode, something other than one or more digits appears in the
   parameter to the REST command).  Any other errors, including such
   problems as restart marker out of range, should be reported when the
   following transfer command is issued.  Such errors will cause that
   transfer request to be rejected with an error indicating the invalid
   restart attempt.

5.4. FEAT Response for REST

Where a server-FTP process supports RESTart in STREAM mode, as specified here, it MUST include, in the response to the FEAT command [6], a line containing exactly the string "REST STREAM". This string is not case sensitive, but it SHOULD be transmitted in upper case. Where REST is not supported at all or supported only in block or compressed modes, the REST line MUST NOT be included in the FEAT response. Where required, the response SHOULD be: C> feat S> 211- <any descriptive text> S> ... S> REST STREAM S> ... S> 211 end The ellipses indicate place holders where other features may be included, and are not required. The one-space indentation of the feature lines is mandatory [6].
Top   ToC   RFC3659 - Page 17

5.5. REST Example

Assume that the transfer of a largish file has previously been interrupted after 802816 octets had been received, that the previous transfer was with TYPE=I, and that it has been verified that the file on the server has not since changed. C> TYPE I S> 200 Type set to I. C> PORT 127,0,0,1,15,107 S> 200 PORT command successful. C> REST 802816 S> 350 Restarting at 802816. Send STORE or RETRIEVE C> RETR cap60.pl198.tar S> 150 Opening BINARY mode data connection [...] S> 226 Transfer complete.


(page 17 continued on part 2)

Next Section