Internet-Draft Rajesh Somasundaran Hewlett Packard Company Expires: August 06, 2004 February 06, 2004 FTP Extensions for recursive and archived file transfers draft-rajeshs-ftpext-rec-arch-transfer-00.txt Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet- Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at The list of Internet-Draft Shadow Directories can be accessed at . Copyright Notice Copyright (C) The Internet Society (2003). All Rights Reserved. Abstract This document describes some extensions to the File Transfer Protocol [1]. These extensions will allow the protocol recursive and archived file transfers. The following new service commands are introduced for FTP: STRC (Store Recursive) RERC (Retrieve Recursive) STAR (Store Archive) REAR (Retrieve Archive) DLST (Directory List) 1. Introduction The File Transfer Protocol [1] provides the ability to transfer only one file per transfer command, in a specified directory. This is Rajesh Somasundaran Expires August 06, 2004 [Page 1] Internet-Draft FTP Extensions Feburary 06 2003 cumbersome process when you need to transfer all the files in a hierarchically structured directory. The new FTP service commands specified in this document offers faster and efficient data transfer while transferring files from a hierarchical directory structure. These commands also eliminate the need for repeated use of commands such as CWD and MKD in these situations. The STAR and REAR commands combined with the "Compressed" transmission mode can offer a much better utilization of bandwidth and time. The terms "pathname", "user-FTP process", "server-FTP process", "user site" and "server site" used in this document bear the same meaning as intended in the File Transfer Protocol [1]. 2. Conventions Used in this Document The key words "REQUIRED", "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" in this document are to be interpreted as described in "Key words for use in RFCs to Indicate Requirement Levels" [3]. 3. STORE RECURSIVE (STRC) This command is a special case of the STOR command which can be used to recursively transfer all the files under a particular directory, till the end of the directory hierarchy. The argument is a pathname specifying a directory or a file. The server site must maintain the hierarchical structure of the directory specified in the pathname. The format of the STRC command is as follows: STRC The server site should be educated about the directory hierarchy before the transfer begins. The recursive data transfer using STRC command must take place in three stages, as follows: 1. The server site should be informed of the directory where the recursive transfer will start. For this, the STRC command must be used with a pathname specifying a directory or other system dependent file group designator. This should be immediately followed by the DLST command in the second stage. 2. The DLST command must be used to pass the hierarchical directory listing. Using this data, The server site should create the directories efficiently. The directory traversal for getting the hierarchical directory listing can be done in any order. The directory listing should be as specified in Appendix I. 3. The actual file transfer begins using the STRC command. In this stage, the pathname used in the argument should be a file name. The user-FTP process should use multiple STRC commands until all the files in the directory hierarchy are transferred. The order of STRC commands and the DLST command must be strictly as Rajesh Somasundaran Expires August 06, 2004 [Page 2] Internet-Draft FTP Extensions Feburary 06 2003 described above. The reply codes for STRC command in the first stage must be same as those of the MKD command [1], if the pathname is non-existent. Otherwise, the reply codes must be same as those of the LIST command [1]. If the directory is newly created, the response should also include the status of its creation. The reply codes for the succeeding STRC commands must be same as those of the STOR command [1]. If the file specified in the pathname exists at the server site, then its contents shall be replaced by the data being transferred. A new file is created at the server site if the file specified in the pathname does not already exist. Similarly, a new directory will be created if the directory specified in the pathname does not exist. A directory in the pathname may be specified in its absolute form or in the relative form. In the latter case, the directory will be created as a subdirectory to the current working directory. 4. RETRIEVE RECURSIVE (RERC) This command is a special case of the RETR command which can be used if all the files under a particular directory need to be transferred recursively till the end of the directory hierarchy. The argument is a pathname specifying a directory or a file. It is the responsibility of the user-FTP process to maintain the same hierarchical structure in the user site as at the server site. The format of the RERC command is as follows: RERC The recursive data transfer using RERC command must take place in the following two stages: 1. The user-FTP process sends RERC command with a pathname specifying a directory or other system dependent file group designator. This pathname indicates the the starting point for the recursive directory transfer. In its reply to the first RERC command, the server-FTP process must send the recursive listing of the specified directory to the user-FTP process. This data should be send across the data connection. The directory traversal for obtaining the hierarchical directory listing can be done in any order. Appendix II specifies the format for such a recursive directory listing. Using this data, the user-FTP process should create the directories efficiently. 2. The actual file transfer begins using the RERC command. In this stage, the pathname used in the argument should be a file name. The user-FTP process should use multiple RERC commands till all the files in the directory hierarchy are transferred. The reply code for the RERC command in the first stage must be same as those of the LIST command [1]. The reply codes for the succeeding RERC commands must be same as those of the RETR command [1]. Rajesh Somasundaran Expires August 06, 2004 [Page 3] Internet-Draft FTP Extensions Feburary 06 2003 A directory in the pathname can be specified in its absolute form or in the relative form. In the latter case, the directory will be considered as a subdirectory to the current working directory. 5. STORE ARCHIVE (STAR) This command is a special case of the STOR command where files and directories are archived and then transferred. The argument is a path name specifying a directory or other system dependent file group designator. The server site should archive the files and directories with the pathname as the beginning of the archive. It is the responsibility of the user-FTP process to extract the files and directories. The extracted files and directories will be stored in the same hierarchical structure as at the server site. The format of the STAR command is as follows: STAR The archiving style depends on the type of operating system at the server. The SYST command can be used to find out the type of operating system at the server. The reply for SYST command shall have as its first word one of the system names listed in the current version of the Assigned Numbers document [2]. The user-FTP process can make any decision on extracting the files and directories based on the archiving style used at the server site. It is the responsibility of the user-FTP process to use the SYST command before using the STAR command to make any such decisions. The reply codes for the STAR command must be same as those of the STOR command [1]. The server response should also include the status of extracting the files and directories from the archive. 6. RETRIEVE ARCHIVE (REAR) This command is a special case of the RETR command where files and directories are archived and transferred. The argument is a pathname specifying a directory or other system dependent file group designator. The user-FTP process should archive the files and directories with the pathname as the beginning of the archive. It is the responsibility of the server site to extract the files and directories. The extracted files and directories will be stored in the same hierarchical structure as at the sending end. The format of the REAR command is as follows: REAR The user-FTP process can make decision on the style of archiving to be used based on the type of operating system at the server site. This can be identified using the SYST command. It is the responsibility of the user-FTP process to use the SYST command before Rajesh Somasundaran Expires August 06, 2004 [Page 4] Internet-Draft FTP Extensions Feburary 06 2003 using the REAR command to make any such decisions. The reply codes for the REAR command must be same as those of the RETR command [1]. The server response should also include the status of archiving. 7. DIRECTORY LIST (DLST) This command must be used to convey the hierarchical directory structure information to the server site in association with the STRC command. The server site should create the directories efficiently using this data. The argument to the DLST command is the hierarchical directory listing. This can be in the form of a recursive directory listing (excluding the files listing). Each individual item in the list except the last should be separated by EOR. The last list item should be ended with EOF. See Appendix I for the format of such a directory hierarchy listing. The DLST command should immediately succeed the STRC command with a pathname specifying a directory name or other system dependent file group designator. The format of the DLST command is as follows: DLST The reply codes for DLST command must be same as those of the MKD command [1]. The response should also include the status of each directory created. Appendix I The format of directory hierarchy listing to be used for educating the server site is as follows: | | |---------------------------------| directory1 directory2 | | | | --------------------- directory5 | | | | directory3 directory4 | | directory6 : directory1 directory2 ./directory1: directory3 Rajesh Somasundaran Expires August 06, 2004 [Page 5] Internet-Draft FTP Extensions Feburary 06 2003 directory4 ./directory1/directory3: directory6 ./directory2: directory5 While sending this data to the server site using DLST, every individual item, except the last item, should be separated by EOR and the last item should end with EOF as follows: :EOR directory1EOR directory2EOR ./directory1:EOR directory3EOR directory4EOR ./directory2:EOR directory5EOR ./directory1/directory3:EOR directory6EOF Appendix II The format of a recursive directory listing to be sent by the server site in response to a RERC command with an argument specifying a directory is as follows: | | |---------------|-----------------| directory1 file1 directory2 | | | | ---------------------- ---------------------- | | | | | | | | directory3 file2 file3 file4 : directory1/ file1 directory2/ ./directory1: directory3/ file2 ./directory2: file3 file4 While sending this data, every individual item, except the last item, should be separated by EOR and the last item should end with EOF specified as follows: Rajesh Somasundaran Expires August 06, 2004 [Page 6] Internet-Draft FTP Extensions Feburary 06 2003 :EOR directory1/EOR file1EOR directory2/EOR ./directory1:EOR directory3/EOR file2EOR ./directory2:EOR file3EOR file4EOF References The following documents contain definitions or specifications that are necessary to understand this document properly: [1] Postel, J., and J. Reynolds, "File Transfer Protocol (FTP)", STD 9, RFC 959, October 1985. [2] Reynolds, Joyce, and Jon Postel, "Assigned Numbers", RFC 943, ISI, April 1985. [3] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. Author's Address Rajesh Somasundaran Hewlett Packard, 29C, Cunningham Road, Bangalore, India 560052 Phone: +91 80 2205 3104 EMail: rajesh.somasundaran@hp.com Intellectual Property Statement The IETF takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on the IETF's procedures with respect to rights in standards-track and standards-related documentation can be found in BCP-11. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF Secretariat. Rajesh Somasundaran Expires August 06, 2004 [Page 7] Internet-Draft FTP Extensions Feburary 06 2003 The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to practice this standard. Please address the information to the IETF Executive Director. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Rajesh Somasundaran Expires August 06, 2004 [Page 8]