diff options
Diffstat (limited to 'crypto/heimdal/doc/standardisation/draft-ietf-ftpext-mlst-08.txt')
| -rw-r--r-- | crypto/heimdal/doc/standardisation/draft-ietf-ftpext-mlst-08.txt | 3415 |
1 files changed, 0 insertions, 3415 deletions
diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-ftpext-mlst-08.txt b/crypto/heimdal/doc/standardisation/draft-ietf-ftpext-mlst-08.txt deleted file mode 100644 index 885cf49..0000000 --- a/crypto/heimdal/doc/standardisation/draft-ietf-ftpext-mlst-08.txt +++ /dev/null @@ -1,3415 +0,0 @@ -FTPEXT Working Group R. Elz -Internet Draft University of Melbourne -Expiration Date: April 2000 - P. Hethmon - Hethmon Brothers - - October 1999 - - - Extensions to FTP - - - draft-ietf-ftpext-mlst-08.txt - -Status of this Memo - - This document is an Internet-Draft and is NOT offered in accordance - with Section 10 of RFC2026, and the author does not provide the IETF - with any rights other than to publish as an Internet-Draft. - - 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 - http://www.ietf.org/ietf/1id-abstracts.txt. - - To view the list Internet-Draft Shadow Directories, see - http://www.ietf.org/shadow.html. - - This entire section has been prepended to this document automatically - during formatting without any direct involvement by the author(s) of - this draft. - - - - - - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 1] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -Abstract - - In order to overcome the problems caused by the undefined format of - the current FTP LIST command output, a new command is needed to - transfer standardized listing information from Server-FTP to User- - FTP. Commands to enable this are defined in this document. - - In order to allow consenting clients and servers to interact more - freely, a quite basic, and optional, virtual file store structure is - defined. - - This proposal also extends the FTP protocol to allow character sets - other than US-ASCII[1] by allowing the transmission of 8-bit - characters and the recommended use of UTF-8[2] encoding. - - Much implemented, but long undocumented, mechanisms to permit - restarts of interrupted data transfers in STREAM mode, are also - included here. - - Lastly, the HOST command has been added to allow a style of "virtual - site" to be constructed. - - Changed in this version of this document: Minor corrections as - discussed on the mailing list, including fixing many typographical - errors; Additional examples. This paragraph will be deleted from the - final version of this document. - - - - - - - - - - - - - - - - - - - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 2] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - - -Table of Contents - - Abstract ................................................ 2 - 1 Introduction ............................................ 4 - 2 Document Conventions .................................... 4 - 2.1 Basic Tokens ............................................ 5 - 2.2 Pathnames ............................................... 5 - 2.3 Times ................................................... 7 - 2.4 Server Replies .......................................... 8 - 3 File Modification Time (MDTM) ........................... 8 - 3.1 Syntax .................................................. 9 - 3.2 Error responses ......................................... 9 - 3.3 FEAT response for MDTM .................................. 9 - 3.4 MDTM Examples ........................................... 10 - 4 File SIZE ............................................... 11 - 4.1 Syntax .................................................. 11 - 4.2 Error responses ......................................... 11 - 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 ............................... 13 - 5.2 Error Recovery and Restart .............................. 14 - 5.3 Syntax .................................................. 14 - 5.4 FEAT response for REST .................................. 16 - 5.5 REST Example ............................................ 16 - 6 Virtual FTP servers ..................................... 16 - 6.1 The HOST command ........................................ 18 - 6.2 Syntax of the HOST command .............................. 18 - 6.3 HOST command semantics .................................. 19 - 6.4 HOST command errors ..................................... 21 - 6.5 FEAT response for HOST command .......................... 22 - 7 A Trivial Virtual File Store (TVFS) ..................... 23 - 7.1 TVFS File Names ......................................... 23 - 7.2 TVFS Path Names ......................................... 24 - 7.3 FEAT Response for TVFS .................................. 25 - 7.4 OPTS for TVFS ........................................... 26 - 7.5 TVFS Examples ........................................... 26 - 8 Listings for Machine Processing (MLST and MLSD) ......... 28 - 8.1 Format of MLSx Requests ................................. 29 - 8.2 Format of MLSx Response ................................. 29 - 8.3 Filename encoding ....................................... 32 - 8.4 Format of Facts ......................................... 33 - 8.5 Standard Facts .......................................... 33 - 8.6 System Dependent and Local Facts ........................ 41 - 8.7 MLSx Examples ........................................... 42 - 8.8 FEAT response for MLSx .................................. 50 - - - -Elz & Hethmon [Expires April 2000] [Page 3] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - 8.9 OPTS parameters for MLST ................................ 51 - 9 Impact On Other FTP Commands ............................ 55 - 10 Character sets and Internationalization ................. 56 - 11 IANA Considerations ..................................... 56 - 11.1 The OS specific fact registry ........................... 56 - 11.2 The OS specific filetype registry ....................... 57 - 12 Security Considerations ................................. 57 - 13 References .............................................. 58 - Acknowledgments ......................................... 59 - Copyright ............................................... 60 - Editors' Addresses ...................................... 60 - - - - -1. Introduction - - This document amends the File Transfer Protocol (FTP) [3]. Five new - commands are added: "SIZE", "HOST", "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, to - support the notion of virtual hosts, 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 path names. - -2. Document Conventions - - This document makes use of the document conventions defined in BCP14 - [4]. That provides the interpretation of capitalized imperative - words like MUST, SHOULD, etc. - - This document also uses notation defined in STD 9 [3]. In - particular, the terms "reply", "user", "NVFS", "file", "pathname", - "FTP commands", "DTP", "user-FTP process", "user-PI", "user-DTP", - "server-FTP process", "server-PI", "server-DTP", "mode", "type", - "NVT", "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 are required throughout the document, - - - -Elz & Hethmon [Expires April 2000] [Page 4] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - those 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. - -2.1. Basic Tokens - - This document imports the core definitions given in Appendix A of - [5]. There definitions will be found for basic ABNF elements like - ALPHA, DIGIT, SP, etc. To that, 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) - - The VCHAR (from [5]), TCHAR, and RCHAR 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. - -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. - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 5] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - pathname = utf-8-name / raw - utf-8-name = <a UTF-8 encoded Unicode string> - raw = <any string not being 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 encoding, and - then attempting to invert the encoding later. Note that ASCII is a - subset of UTF-8. - - 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]. - - Implementations should also beware that the 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. - - 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 7) 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. - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 6] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -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 filename 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. - - 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. - - - - -Elz & Hethmon [Expires April 2000] [Page 7] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - The technical differences between 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 (which was not used in - [3]) used in this document, and other FTP related documents, - 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 be of 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". - -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 which can be provided in the result from - the new MLST command is recommended as a superior alternative. - - When attempting to restart a RETRieve, if the User-FTP makes use of - the MDTM command, or "modify" fact, it can check and see 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. - - 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 - - - -Elz & Hethmon [Expires April 2000] [Page 8] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - changed and it would be unsafe to restart the file transfer. - - 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 which may be the - object of a RETR command. Attempts to query the modification time of - files that are unable to be retrieved generate undefined responses. - - 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 - -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]. - -3.3. FEAT response for MDTM - - When replying to the FEAT command [6], an FTP server 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 - - - - -Elz & Hethmon [Expires April 2000] [Page 9] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - 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, and 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, and a directory - D, and no other files at all, then the MTDM 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 21 - days and several hours later. - - 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 - - - -Elz & Hethmon [Expires April 2000] [Page 10] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - 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. That is, the exact - number of octets (8 bit bytes) which 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 a data connection which 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. 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. - - size-response = "213" SP 1*DIGIT CRLF / - error-response - -4.2. Error responses - - Where the command is correctly parsed, but the size is not available, - either 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]. - - - -Elz & Hethmon [Expires April 2000] [Page 11] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -4.3. FEAT response for SIZE - - When replying to the FEAT command [6], an FTP server 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: - - 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 8.5.7) ought be - requested. - - - -Elz & Hethmon [Expires April 2000] [Page 12] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -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 be able 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 RFC 959 - [3]. See section 4.1.3.4 of RFC 1123 [9] for the corrections. - -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. - - - -Elz & Hethmon [Expires April 2000] [Page 13] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - 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 - 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 filename is rarely - going to be useful. If APPE (append) is permitted, it MUST act - - - -Elz & Hethmon [Expires April 2000] [Page 14] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - 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. If it chooses to use the data obtained other than to - complete an earlier transfer, or if it chooses to re-retrieve data - that had been retrieved before, that is its choice. 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 which 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. - - The REST command must be the last command issued before the data - transfer command which is to cause a restarted rather than 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 which 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 the restart marker value is - syntactically invalid for the current transfer mode. That is, in - STREAM mode, if 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. - - - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 15] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -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 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]. - -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. - -6. Virtual FTP servers - - It has become common in the Internet for many domain names to be - allocated to a single IP address. This has introduced the concept of - a "virtual host", where a host appears to exist as an independent - entity, but in reality shares all of its resources with one, or more, - other such hosts. - - - - - -Elz & Hethmon [Expires April 2000] [Page 16] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - Such an arrangement presents some problems for FTP Servers, as all - the FTP Server can detect is an incoming FTP connection to a - particular IP address. That is, all domain names which share the IP - address also share the FTP server, and more importantly, its NVFS. - This means that the various virtual hosts cannot offer different - virtual file systems to clients, nor can they offer different - authentication systems. - - No scheme can overcome this without modifications of some kind to the - user-PI and the user-FTP process. That process is the only entity - that knows which virtual host is required. It has performed the - domain name to IP address translation, and thus has the original - domain name available. - - One method which could be used to allow a style of virtual host would - be for the client to simply send a "CWD" command after connecting, - using the virtual host name as the argument to the CWD command. This - would allow the server-FTP process to implement the file stores of - the virtual hosts as sub-directories in its NVFS. This is simple, - and supported by essentially all server-FTP implementations without - requiring any code changes. - - While that method is simple to describe, and to implement, it suffers - from several drawbacks. First, the "CWD" command is available only - after the user-PI has authenticated itself to the server-FTP process. - Thus, all virtual hosts would be required to share a common - authentication scheme. Second, either the server-FTP process needs - to be modified to understand the special nature of this first CWD - command, negating most of the advantage of this scheme, or all users - must see the same identical NVFS view upon connecting (they must - connect in the same initial directory) or the NVFS must implement the - full set of virtual host directories at each possible initial - directory for any possible user, or the virtual host will not be - truly transparent. Third, and again unless the server is specially - modified, a user connecting this way to a virtual host would be able - to trivially move to any other virtual host supported at the same - server-FTP process, exposing the nature of the virtual host. - - Other schemes overloading other existing FTP commands have also been - proposed. None of those have sufficient merit to be worth - discussion. - - The conclusion from the examination of the possibilities seems to be - that to obtain an adequate emulation of "real" FTP servers, server - modifications to support virtual hosts are required. A new command - seems most likely to provide the support required. - - - - - -Elz & Hethmon [Expires April 2000] [Page 17] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -6.1. The HOST command - - A new command "HOST" is added to the FTP command set to allow - server-FTP process to determine to which of possibly many virtual - hosts the client wishes to connect. This command is intended to be - issued before the user is authenticated, allowing the authentication - scheme, and set of legal users, to be dependent upon the virtual host - chosen. Server-FTP processes may, if they desire, permit the HOST - command to be issued after the user has been authenticated, or may - treat that as an erroneous sequence of commands. The behavior of the - server-FTP process which does allow late HOST commands is undefined. - One reasonable interpretation would be for the user-PI to be returned - to the state that existed after the TCP connection was first - established, before user authentication. - - Servers should note that the response to the HOST command is a - sensible time to send their "welcome" message. This allows the - message to be personalized for any virtual hosts that are supported, - and also allows the client to have determined supported languages, or - representations, for the message, and other messages, via the FEAT - response, and selected an appropriate one via the LANG command. See - [7] for more information. - -6.2. Syntax of the HOST command - - The HOST command is defined as follows. - - host-command = "Host" SP hostname CRLF - hostname = 1*DNCHAR 1*( "." 1*DNCHAR ) [ "." ] - DNCHAR = ALPHA / DIGIT / "-" / "_" / "$" / - "!" / "%" / "[" / "]" / ":" - host-response = host-ok / error-response - host-ok = "220" [ SP *TCHAR ] CRLF - - As with all FTP commands, the "host" command word is case - independent, and may be specified in any character case desired. - - The "hostname" given as a parameter specifies the virtual host to - which access is desired. It should normally be the same name that - was used to obtain the IP address to which the FTP control connection - was made, after any client conversions to convert an abbreviated or - local alias to a complete (fully qualified) domain name, but before - resolving a DNS alias (owner of a CNAME resource record) to its - canonical name. - - If the client was given a network literal address, and consequently - was not required to derive it from a hostname, it should send the - HOST command with the network address, as specified to it, enclosed - - - -Elz & Hethmon [Expires April 2000] [Page 18] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - in brackets (after eliminating any syntax, which might also be - brackets, but is not required to be, from which the server deduced - that a literal address had been specified.) That is, for example - - HOST [10.1.2.3] - - should be sent if the client had been instructed to connect to - "10.1.2.3", or "[10.1.2.3]", or perhaps even IPv4:10.1.2.3. The - method of indicating to a client that a literal address is to be used - is beyond the scope of this specification. - - The parameter is otherwise to be treated as a "complete domain name", - as that term is defined in section 3.1 of RFC 1034 [10]. That - implies that the name is to be treated as a case independent string, - in that upper case ASCII characters are to be treated as equivalent - to the corresponding lower case ASCII characters, but otherwise - preserved as given. It also implies some limits on the length of the - parameter and of the components that create its internal structure. - Those limits are not altered in any way here. - - RFC 1034 imposes no other restrictions upon what kinds of names can - be stored in the DNS. Nor does RFC 1035. This specification, - however, allows only a restricted set of names for the purposes of - the HOST command. Those restrictions can be inferred from the ABNF - grammar given for the "hostname". - -6.3. HOST command semantics - - Upon receiving the HOST command, before authenticating the user-PI, a - server-FTP process should validate that the hostname given represents - a valid virtual host for that server, and if so, establish the - appropriate environment for that virtual host. The meaning of that - is not specified here, and may range from doing nothing at all, or - performing a simple change of working directory, to much more - elaborate state changes, as required. - - If the hostname specified is unknown at the server, or if the server - is otherwise unwilling to treat the particular connection as a - connection to the hostname specified, the server will respond with a - 504 reply. - - Note: servers may require that the name specified is in some sense - equivalent to the particular network address that was used to reach - the server. - - If the hostname specified would normally be acceptable, but for any - reason is temporarily unavailable, the server SHOULD reply to the - HOST command with a 434 reply. - - - -Elz & Hethmon [Expires April 2000] [Page 19] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - The "220" reply code for the HOST command is the same as the code - used on the initial connection established "welcome" message. This - is done deliberately so as to allow the implementation to implement - the front end FTP server as a wrapper which simply waits for the HOST - command, and then invokes an older, RFC959 compliant, server in the - appropriate environment for the particular hostname received. - -6.3.1. The REIN command - - As specified in [3], the REIN command returns the state of the - connection to that it was immediately after the transport connection - was opened. That is not changed here. The effect of a HOST command - will be lost if a REIN command is performed, a new HOST command must - be issued. - - Implementors of user-FTP should be aware that server-FTP - implementations which implement the HOST command as a wrapper around - older implementations will be unable to correctly implement the REIN - command. In such an implementation, REIN will typically return the - server-FTP to the state that existed immediately after the HOST - command was issued, instead of to the state immediately after the - connection was opened. - -6.3.2. User-PI usage of HOST - - A user-PI that conforms to this specification, MUST send the HOST - command after opening the transport connection, or after any REIN - command, before attempting to authenticate the user with the USER - command. - - The following state diagram shows a typical sequence of flow of - control, where the "B" (begin) state is assumed to occur after the - transport connection has opened, or a REIN command has succeeded. - Other commands (such as FEAT [6]) which require no authentication may - have intervened. This diagram is modeled upon (and largely borrowed - from) the similar diagram in section 6 of [3]. - - In this diagram, a three digit reply indicates that precise server - reply code, a single digit on a reply path indicates any server reply - beginning with that digit, other than any three digit replies that - might take another path. - - - - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 20] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - - +---+ HOST +---+ 1,3,5 - | B |---------->| W |----------------- - +---+ +---+ | - | | | - 2,500,502 | | 4,501,503,504 | - -------------- ------------- | - | | | - V 1 | V - +---+ USER +---+-------------->+---+ - | |---------->| W | 2 ----->| E | - +---+ +---+------ | --->+---+ - | | | | | | - 3 | | 4,5 | | | | - -------------- ----- | | | | - | | | | | | - | | | | | | - | --------- | | - | 1| | | | | - V | | | | | - +---+ PASS +---+ 2 | ------->+---+ - | |---------->| W |-------------->| S | - +---+ +---+ ----------->+---+ - | | | | | | - 3 | |4,5| | | | - -------------- -------- | | - | | | | | ---- - | | | | | | - | ----------- | - | 1,3| | | | | - V | 2| | | V - +---+ ACCT +---+-- | ------>+---+ - | |---------->| W | 4,5 --------->| F | - +---+ +---+-------------->+---+ - -6.4. HOST command errors - - The server-PI shall reply with a 500 or 502 reply if the HOST command - is unrecognized or unimplemented. A 503 reply may be sent if the - HOST command is given after a previous HOST command, or after a user - has been authenticated. Alternately, the server may accept the - command at such a time, with server defined behavior. A 501 reply - should be sent if the hostname given is syntactically invalid, and a - 504 reply if a syntactically valid hostname is not a valid virtual - host name for the server. - - In all such cases the server-FTP process should act as if no HOST - command had been given. - - - -Elz & Hethmon [Expires April 2000] [Page 21] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - A user-PI receiving a 500 or 502 reply should assume that the - server-PI does not implement the HOST command style virtual server. - It may then proceed to login as if the HOST command had succeeded, - and perhaps, attempt a CWD command to the hostname after - authenticating the user. - - A user-PI receiving some other error reply should assume that the - virtual HOST is unavailable, and terminate communications. - - A server-PI that receives a USER command, beginning the - authentication sequence, without having received a HOST command - SHOULD NOT reject the USER command. Clients conforming to earlier - FTP specifications do not send HOST commands. In this case the - server may act as if some default virtual host had been explicitly - selected, or may enter an environment different from that of all - supported virtual hosts, perhaps one in which a union of all - available accounts exists, and which presents a NVFS which appears to - contain sub-directories containing the NVFS for all virtual hosts - supported. - -6.5. FEAT response for HOST command - - A server-FTP process that supports the host command, and virtual FTP - servers, MUST include in the response to the FEAT command [6], a - feature line indicating that the HOST command is supported. This - line should contain the single word "HOST". 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> HOST - 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]. - - - - - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 22] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -7. A Trivial Virtual File Store (TVFS) - - Traditionally, FTP has placed almost no constraints upon the file - store (NVFS) provided by a server. This specification does not alter - that. However, it has become common for servers to attempt to - provide at least file system naming conventions modeled loosely upon - those of the UNIX(TM) file system. That is, a tree structured file - system, built of directories, each of which can contain other - directories, or other kinds of files, or both. Each file and - directory has a file name relative to the directory that contains it, - except for the directory at the root of the tree, which is contained - in no other directory, and hence has no name of its own. - - That which has so far been described is perfectly consistent with the - standard FTP NVFS and access mechanisms. The "CWD" command is used - to move from one directory to an embedded directory. "CDUP" may be - provided to return to the parent directory, and the various file - manipulation commands ("RETR", "STOR", the rename commands, etc) are - used to manipulate files within the current directory. - - However, it is often useful to be able to reference files other than - by changing directories, especially as FTP provides no guaranteed - mechanism to return to a previous directory. The Trivial Virtual - File Store (TVFS), if implemented, provides that mechanism. - -7.1. TVFS File Names - - Where a server implements the TVFS, no elementary filename shall - contain the character "/". Where the underlying natural file store - permits files, or directories, to contain the "/" character in their - names, a server-PI implementing TVFS must encode that character in - some manner whenever file or directory names are being returned to - the user-PI, and reverse that encoding whenever such names are being - accepted from the user-PI. - - The encoding method to be used is not specified here. Where some - other character is illegal in file and directory names in the - underlying file store, a simple transliteration may be sufficient. - Where there is no suitable substitute character a more complex - encoding scheme, possibly using an escape character, is likely to be - required. - - With the one exception of the unnamed root directory, a TVFS file - name may not be empty. That is, all other file names contain at - least one character. - - With the sole exception of the "/" character, any valid IS10646 - character [11] may be used in a TVFS filename. When transmitted, - - - -Elz & Hethmon [Expires April 2000] [Page 23] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - file name characters are encoded using the UTF-8 encoding [2]. - -7.2. TVFS Path Names - - A TVFS "Path Name" combines the file or directory name of a target - file or directory, with the directory names of zero or more enclosing - directories, so as to allow the target file or directory to be - referenced other than when the server's "current working directory" - is the directory directly containing the target file or directory. - - By definition, every TVFS file or directory name is also a TVFS path - name. Such a path name is valid to reference the file from the - directory containing the name, that is, when that directory is the - server-FTP's current working directory. - - Other TVFS path names are constructed by prefixing a path name by a - name of a directory from which the path is valid, and separating the - two with the "/" character. Such a path name is valid to reference - the file or directory from the directory containing the newly added - directory name. - - Where a path name has been extended to the point where the directory - added is the unnamed root directory, the path name will begin with - the "/" character. Such a path is known as a fully qualified path - name. Fully qualified paths may, obviously, not be further extended, - as, by definition, no directory contains the root directory. Being - unnamed, it cannot be represented in any other directory. A fully - qualified path name is valid to reference the named file or directory - from any location (that is, regardless of what the current working - directory may be) in the virtual file store. - - Any path name which is not a fully qualified path name may be - referred to as a "relative path name" and will only correctly - reference the intended file when the current working directory of the - server-FTP is a directory from which the relative path name is valid. - - As a special case, the path name "/" is defined to be a fully - qualified path name referring to the root directory. That is, the - root directory does not have a directory (or file) name, but does - have a path name. This special path name may be used only as is as a - reference to the root directory. It may not be combined with other - path names using the rules above, as doing so would lead to a path - name containing two consecutive "/" characters, which is an undefined - sequence. - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 24] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -7.2.1. Notes - - + It is not required, or expected, that there be only one fully - qualified path name that will reference any particular file or - directory. - + As a caveat, though the TVFS file store is basically tree - structured, there is no requirement that any file or directory - have only one parent directory. - + As defined, no TVFS path name will ever contain two consecutive - "/" characters. Such a name is not illegal however, and may be - defined by the server for any purpose that suits it. Clients - implementing this specification should not assume any semantics - at all for such names. - + Similarly, other than the special case path that refers to the - root directory, no TVFS path name constructed as defined here - will ever end with the "/" character. Such names are also not - illegal, but are undefined. - + While any legal IS10646 character is permitted to occur in a TVFS - file or directory name, other than "/", server FTP - implementations are not required to support all possible IS10646 - characters. The subset supported is entirely at the discretion - of the server. The case (where it exists) of the characters that - make up file, directory, and path names may be significant. - Unless determined otherwise by means unspecified here, clients - should assume that all such names are comprised of characters - whose case is significant. Servers are free to treat case (or - any other attribute) of a name as irrelevant, and hence map two - names which appear to be distinct onto the same underlying file. - + There are no defined "magic" names, like ".", ".." or "C:". - Servers may implement such names, with any semantics they choose, - but are not required to do so. - + TVFS imposes no particular semantics or properties upon files, - guarantees no access control schemes, or any of the other common - properties of a file store. Only the naming scheme is defined. - -7.3. FEAT Response for TVFS - - In response to the FEAT command [6] a server that wishes to indicate - support for the TVFS as defined here will include a line that begins - with the four characters "TVFS" (in any case, or mixture of cases, - upper case is not required). Servers SHOULD send upper case. - - Such a response to the FEAT command MUST NOT be returned unless the - server implements TVFS as defined here. - - Later specifications may add to the TVFS definition. Such additions - should be notified by means of additional text appended to the TVFS - feature line. Such specifications, if any, will define the extra - - - -Elz & Hethmon [Expires April 2000] [Page 25] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - text. - - Until such a specification is defined, servers should not include - anything after "TVFS" in the TVFS feature line. Clients, however, - should be prepared to deal with arbitrary text following the four - defined characters, and simply ignore it if unrecognized. - - A typical response to the FEAT command issued by a server - implementing only this specification would be: - - C> feat - S> 211- <any descriptive text> - S> ... - S> TVFS - 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], and is not counted as one of the - first four characters for the purposes of this feature listing. - - The TVFS feature adds no new commands to the FTP command repertoire. - -7.4. OPTS for TVFS - - There are no options in this TVFS specification, and hence there is - no OPTS command defined. - -7.5. TVFS Examples - - Assume a TVFS file store is comprised of a root directory, which - contains two directories (A and B) and two non-directory files (X and - Y). The A directory contains two directories (C and D) and one other - file (Z). The B directory contains just two non-directory files (P - and Q) and the C directory also two non-directory files (also named P - and Q, by chance). The D directory is empty, that is, contains no - files or directories. - - - - - - - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 26] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - This structure may depicted graphically as... - - (unnamed root) - / | \ \ - / | \ \ - A X B Y - /|\ / \ - / | \ / \ - C D Z P Q - / \ - / \ - P Q - - Given this structure, the following fully qualified path names exist. - - / - /A - /B - /X - /Y - /A/C - /A/D - /A/Z - /A/C/P - /A/C/Q - /B/P - /B/Q - - It is clear that none of the paths / /A /B or /A/D refer to the same - directory, as the contents of each is different. Nor do any of / /A - /A/C or /A/D. However /A/C and /B might be the same directory, there - is insufficient information given to tell. Any of the other path - names (/X /Y /A/Z /A/C/P /A/C/Q /B/P and /B/Q) may refer to the same - underlying files, in almost any combination. - - If the current working directory of the server-FTP is /A then the - following path names, in addition to all the fully qualified path - names, are valid - - C - D - Z - C/P - C/Q - - These all refer to the same files or directories as the corresponding - fully qualified path with "/A/" prepended. - - - - -Elz & Hethmon [Expires April 2000] [Page 27] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - That those path names all exist does not imply that the TVFS sever - will necessarily grant any kind of access rights to the named paths, - or that access to the same file via different path names will - necessarily be granted equal rights. - - None of the following relative paths are valid when the current - directory is /A - - A - B - X - Y - B/P - B/Q - P - Q - - Any of those could be made valid by changing the server-FTP's current - working directory to the appropriate directory. Note that the paths - "P" and "Q" might refer to different files depending upon which - directory is selected to cause those to become valid TVFS relative - paths. - -8. Listings for Machine Processing (MLST and MLSD) - - The MLST and MLSD commands are intended to standardize the file and - directory information returned by the Server-FTP process. These - commands differ from the LIST command in that the format of the - replies is strictly defined although extensible. - - Two commands are defined, MLST which provides data about exactly the - object named on its command line, and no others. MLSD on the other - hand will list the contents of a directory if a directory is named, - otherwise a 501 reply will be returned. In either case, if no object - is named, the current directory is assumed. That will cause MLST to - send a one line response, describing the current directory itself, - and MLSD to list the contents of the current directory. - - In the following, the term MLSx will be used wherever either MLST or - MLSD may be inserted. - - The MLST and MLSD commands also extend the FTP protocol as presented - in RFC 959 [3] and RFC 1123 [9] to allow that transmission of 8-bit - data over the control connection. Note this is not specifying - character sets which are 8-bit, but specifying that FTP - implementations are to specifically allow the transmission and - reception of 8-bit bytes, with all bits significant, over the control - connection. That is, all 256 possible octet values are permitted. - - - -Elz & Hethmon [Expires April 2000] [Page 28] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - The MLSx command allows both UTF-8/Unicode and "raw" forms as - arguments, and in responses both to the MLST and MLSD commands, and - all other FTP commands which take pathnames as arguments. - -8.1. Format of MLSx Requests - - The MLST and MLSD commands each allow a single optional argument. - This argument may be either a directory name or, for MLST only, a - filename. For these purposes, a "filename" is the name of any entity - in the server NVFS which is not a directory. Where TVFS is - supported, any TVFS relative path name valid in the current working - directory, or any TVFS fully qualified path name, may be given. If a - directory name is given then MLSD must return a listing of the - contents of the named directory, otherwise it issues a 501 reply, and - does not open a data connection. In all cases for MLST, a single set - of fact lines (usually a single fact line) containing the information - about the named file or directory shall be returned over the control - connection, without opening a data connection. - - If no argument is given then MLSD must return a listing of the - contents of the current working directory, and MLST must return a - listing giving information about the current working directory - itself. For these purposes, the contents of a directory are whatever - filenames (not pathnames) the server-PI will allow to be referenced - when the current working directory is the directory named, and which - the server-PI desires to reveal to the user-PI. - - No title, header, or summary, lines, or any other formatting, other - than as is specified below, is ever returned in the output of an MLST - or MLSD command. - - If the Client-FTP sends an invalid argument, the Server-FTP MUST - reply with an error code of 501. - - The syntax for the MLSx command is: - - mlst = "MLst" [ SP pathname ] CRLF - mlsd = "MLsD" [ SP pathname ] CRLF - -8.2. Format of MLSx Response - - The format of a response to an MLSx command is as follows: - - mlst-response = control-response / error-response - mlsd-response = ( initial-response final-response ) / - error-response - - - - - -Elz & Hethmon [Expires April 2000] [Page 29] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - control-response = "250-" [ response-message ] CRLF - 1*( SP entry CRLF ) - "250" [ SP response-message ] CRLF - - initial-response = "150" [ SP response-message ] CRLF - final-response = "226" SP response-message CRLF - - response-message = *TCHAR - - data-response = *( entry CRLF ) - - entry = [ facts ] SP pathname - facts = 1*( fact ";" ) - fact = factname "=" value - factname = "Size" / "Modify" / "Create" / - "Type" / "Unique" / "Perm" / - "Lang" / "Media-Type" / "CharSet" / - os-depend-fact / local-fact - os-depend-fact = <IANA assigned OS name> "." token - local-fact = "X." token - value = *RCHAR - - Upon receipt of a MLSx command, the server will verify the parameter, - and if invalid return an error-response. For this purpose, the - parameter should be considered to be invalid if the client issuing - the command does not have permission to perform the request - operation. - - If valid, then for an MLST command, the server-PI will send the first - (leading) line of the control response, the entry for the pathname - given, or the current directory if no pathname was provided, and the - terminating line. Normally exactly one entry would be returned, more - entries are permitted only when required to represent a file that is - to have multiple "Type" facts returned. - - Note that for MLST the fact set is preceded by a space. That is - provided to guarantee that the fact set cannot be accidentally - interpreted as the terminating line of the control response, but is - required even when that would not be possible. Exactly one space - exists between the set of facts and the pathname. Where no facts are - present, there will be exactly two leading spaces before the - pathname. No spaces are permitted in the facts, any other spaces in - the response are to be treated as being a part of the pathname. - - If the command was an MLSD command, the server will open a data - connection as indicated in section 3.2 of RFC959 [3]. If that fails, - the server will return an error-response. If all is OK, the server - will return the initial-response, send the appropriate data-response - - - -Elz & Hethmon [Expires April 2000] [Page 30] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - over the new data connection, close that connection, and then send - the final-response over the control connection. The grammar above - defines the format for the data-response, which defines the format of - the data returned over the data connection established. - - The data connection opened for a MLSD response shall be a connection - as if the "TYPE L 8", "MODE S", and "STRU F" commands had been given, - whatever FTP transfer type, mode and structure had actually been set, - and without causing those settings to be altered for future commands. - That is, this transfer type shall be set for the duration of the data - connection established for this command only. While the content of - the data sent can be viewed as a series of lines, implementations - should note that there is no maximum line length defined. - Implementations should be prepared to deal with arbitrarily long - lines. - - The facts part of the specification would contain a series of "file - facts" about the file or directory named on the same line. Typical - information to be presented would include file size, last - modification time, creation time, a unique identifier, and a - file/directory flag. - - The complete format for a successful reply to the MLSD command would - be: - - facts SP pathname CRLF - facts SP pathname CRLF - facts SP pathname CRLF - ... - - Note that the format is intended for machine processing, not human - viewing, and as such the format is very rigid. Implementations MUST - NOT vary the format by, for example, inserting extra spaces for - readability, replacing spaces by tabs, including header or title - lines, or inserting blank lines, or in any other way alter this - format. Exactly one space is always required after the set of facts - (which may be empty). More spaces may be present on a line if, and - only if, the file name presented contains significant spaces. The - set of facts must not contain any spaces anywhere inside it. Facts - should be provided in each output line only if they both provide - relevant information about the file named on the same line, and they - are in the set requested by the user-PI. There is no requirement - that the same set of facts be provided for each file, or that the - facts presented occur in the same order for each file. - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 31] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -8.3. Filename encoding - - An FTP implementation supporting the MLSx commands must be 8-bit - clean. This is necessary in order to transmit UTF-8 encoded - filenames. This specification recommends the use of UTF-8 encoded - filenames. FTP implementations SHOULD use UTF-8 whenever possible to - encourage the maximum interoperability. - - Filenames are not restricted to UTF-8, however treatment of arbitrary - character encodings is not specified by this standard. Applications - are encouraged to treat non-UTF-8 encodings of filenames as octet - sequences. - - Note that this encoding is unrelated to that of the contents of the - file, even if the file contains character data. - - Further information about filename encoding for FTP may be found in - "Internationalization of the File Transfer Protocol" [7]. - -8.3.1. Notes about the Filename - - The filename returned in the MLST response should be the same name as - was specified in the MLST command, or, where TVFS is supported, a - fully qualified TVFS path naming the same file. Where no argument - was given to the MLST command, the server-PI may either include an - empty filename in the response, or it may supply a name that refers - to the current directory, if such a name is available. Where TVFS is - supported, a fully qualified path name of the current directory - SHOULD be returned. - - Filenames returned in the output from an MLSD command SHOULD be - unqualified names within the directory named, or the current - directory if no argument was given. That is, the directory named in - the MLSD command SHOULD NOT appear as a component of the filenames - returned. - - If the server-FTP process is able, and the "type" fact is being - returned, it MAY return in the MLSD response, an entry whose type is - "cdir", which names the directory from which the contents of the - listing were obtained. Where TVFS is supported, the name MAY be the - fully qualified path name of the directory, or MAY be any other path - name which is valid to refer to that directory from the current - working directory of the server-FTP. Where more than one name - exists, multiple of these entries may be returned. In a sense, the - "cdir" entry can be viewed as a heading for the MLSD output. - However, it is not required to be the first entry returned, and may - occur anywhere within the listing. - - - - -Elz & Hethmon [Expires April 2000] [Page 32] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - When TVFS is supported, a user-PI can refer to any file or directory - in the listing by combining a type "cdir" name, with the appropriate - name from the directory listing using the procedure defined in - section 7.2. - - Alternatively, whether TVFS is supported or not, the user-PI can - issue a CWD command ([3]) giving a name of type "cdir" from the - listing returned, and from that point reference the files returned in - the MLSD response from which the cdir was obtained by using the - filename components of the listing. - -8.4. Format of Facts - - The "facts" for a file in a reply to a MLSx command consist of - information about that file. The facts are a series of keyword=value - pairs each followed by semi-colon (";") characters. An individual - fact may not contain a semi-colon in its name or value. The complete - series of facts may not contain the space character. See the - definition or "RCHAR" in section 2.1 for a list of the characters - that can occur in a fact value. Not all are applicable to all facts. - - A sample of a typical series of facts would be: (spread over two - lines for presentation here only) - - size=4161;lang=en-US;modify=19970214165800;create=19961001124534; - type=file;x.myfact=foo,bar; - -8.5. Standard Facts - - This document defines a standard set of facts as follows: - - size -- Size in octets - modify -- Last modification time - create -- Creation time - type -- Entry type - unique -- Unique id of file/directory - perm -- File permissions, whether read, write, execute is - allowed for the login id. - lang -- Language of the filename per IANA[12] registry. - media-type -- MIME media-type of file contents per IANA registry. - charset -- Character set per IANA registry (if not UTF-8) - - Fact names are case-insensitive. Size, size, SIZE, and SiZe are the - same fact. - - Further operating system specific keywords could be specified by - using the IANA operating system name as a prefix (examples only): - - - - -Elz & Hethmon [Expires April 2000] [Page 33] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - OS/2.ea -- OS/2 extended attributes - MACOS.rf -- MacIntosh resource forks - UNIX.mode -- Unix file modes (permissions) - - Implementations may define keywords for experimental, or private use. - All such keywords MUST begin with the two character sequence "x.". - As type names are case independent, "x." and "X." are equivalent. - For example: - - x.ver -- Version information - x.desc -- File description - x.type -- File type - -8.5.1. The type Fact - - The type fact needs a special description. Part of the problem with - current practices is deciding when a file is a directory. If it is a - directory, is it the current directory, a regular directory, or a - parent directory? The MLST specification makes this unambiguous - using the type fact. The type fact given specifies information about - the object listed on the same line of the MLST response. - - Five values are possible for the type fact: - - file -- a file entry - cdir -- the listed directory - pdir -- a parent directory - dir -- a directory or sub-directory - OS.name=type -- an OS or file system dependent file type - - The syntax is defined to be: - - type-fact = type-label "=" type-val - type-label = "Type" - type-val = "File" / "cdir" / "pdir" / "dir" / - os-type - -8.5.1.1. type=file - - The presence of the type=file fact indicates the listed entry is a - file containing non-system data. That is, it may be transferred from - one system to another of quite different characteristics, and perhaps - still be meaningful. - -8.5.1.2. type=cdir - - The type=cdir fact indicates the listed entry contains a pathname of - the directory whose contents are listed. An entry of this type will - - - -Elz & Hethmon [Expires April 2000] [Page 34] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - only be returned as a part of the result of an MLSD command when the - type fact is included, and provides a name for the listed directory, - and facts about that directory. In a sense, it can be viewed as - representing the title of the listing, in a machine friendly format. - It may appear at any point of the listing, it is not restricted to - appearing at the start, though frequently may do so, and may occur - multiple times. It MUST NOT be included if the type fact is not - included, or there would be no way for the user-PI to distinguish the - name of the directory from an entry in the directory. - - Where TVFS is supported by the server-FTP, this name may be used to - construct path names with which to refer to the files and directories - returned in the same MLSD output (see section 7.2). These path names - are only expected to work when the server-PI's position in the NVFS - file tree is the same as its position when the MLSD command was - issued, unless a fully qualified path name results. - - Where TVFS is not supported, the only defined semantics associated - with a "type=cdir" entry are that, provided the current working - directory of the server-PI has not been changed, a pathname of type - "cdir" may be used as an argument to a CWD command, which will cause - the current directory of the server-PI to change so that the - directory which was listed in its current working directory. - -8.5.1.3. type=dir - - If present, the type=dir entry gives the name of a directory. Such - an entry typically cannot be transferred from one system to another - using RETR, etc, but should (permissions permitting) be able to be - the object of an MLSD command. - -8.5.1.4. type=pdir - - If present, which will occur only in the response to a MLSD command - when the type fact is included, the type=pdir entry represents a - pathname of the parent directory of the listed directory. As well as - having the properties of a type=dir, a CWD command that uses the - pathname from this entry should change the user to a parent directory - of the listed directory. If the listed directory is the current - directory, a CDUP command may also have the effect of changing to the - named directory. User-FTP processes should note not all responses - will include this information, and that some systems may provide - multiple type=pdir responses. - - Where TVFS is supported, a "type=pdir" name may be a relative path - name, or a fully qualified path name. A relative path name will be - relative to the directory being listed, not to the current directory - of the server-PI at the time. - - - -Elz & Hethmon [Expires April 2000] [Page 35] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - For the purposes of this type value, a "parent directory" is any - directory in which there is an entry of type=dir which refers to the - directory in which the type=pdir entity was found. Thus it is not - required that all entities with type=pdir refer to the same - directory. The "unique" fact (if supported) can be used to determine - whether there is a relationship between the type=pdir entries or not. - -8.5.1.5. System defined types - - Files types that are specific to a specific operating system, or file - system, can be encoded using the "OS." type names. The format is: - - os-type = "OS." os-name "=" os-type - os-name = <an IANA registered operating system name> - os-type = token - - The "os-name" indicates the specific system type which supports the - particular localtype. OS specific types are registered by the IANA - using the procedures specified in section 11. The "os-type" provides - the system dependent information as to the type of the file listed. - The os-name and os-type strings in an os-type are case independent. - "OS.unix=block" and "OS.Unix=BLOCK" represent the same type (or - would, if such a type were registered.) - - Note: Where the underlying system supports a file type which is - essentially an indirect pointer to another file, the NVFS - representation of that type should normally be to represent the file - which the reference indicates. That is, the underlying basic file - will appear more than once in the NVFS, each time with the "unique" - fact (see immediately following section) containing the same value, - indicating that the same file is represented by all such names. - User-PIs transferring the file need then transfer it only once, and - then insert their own form of indirect reference to construct - alternate names where desired, or perhaps even copy the local file if - that is the only way to provide two names with the same content. A - file which would be a reference to another file, if only the other - file actually existed, may be represented in any OS dependent manner - appropriate, or not represented at all. - -8.5.1.6. Multiple types - - Where a file is such that it may validly, and sensibly, treated by - the server-PI as being of more than one of the above types, then - multiple entries should be returned, each with its own "Type" fact of - the appropriate type, and each containing the same pathname. This - may occur, for example, with a structured file, which may contain - sub-files, and where the server-PI permits the structured file to be - treated as a unit, or treated as a directory allowing the sub-files - - - -Elz & Hethmon [Expires April 2000] [Page 36] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - within it to be referenced. - -8.5.2. The unique Fact - - The unique fact is used to present a unique identifier for a file or - directory in the NVFS accessed via a server-FTP process. The value - of this fact should be the same for any number of pathnames that - refer to the same underlying file. The fact should have different - values for names which reference distinct files. The mapping between - files, and unique fact tokens should be maintained, and remain - consistent, for at least the lifetime of the control connection from - user-PI to server-PI. - - unique-fact = "Unique" "=" token - - This fact would be expected to be used by Server-FTPs whose host - system allows things such as symbolic links so that the same file may - be represented in more than one directory on the server. The only - conclusion that should be drawn is that if two different names each - have the same value for the unique fact, they refer to the same - underlying object. The value of the unique fact (the token) should - be considered an opaque string for comparison purposes, and is a case - dependent value. The tokens "A" and "a" do not represent the same - underlying object. - -8.5.3. The modify Fact - - The modify fact is used to determine the last time the content of the - file (or directory) indicated was modified. Any change of substance - to the file should cause this value to alter. That is, if a change - is made to a file such that the results of a RETR command would - differ, then the value of the modify fact should alter. User-PIs - should not assume that a different modify fact value indicates that - the file contents are necessarily different than when last retrieved. - Some systems may alter the value of the modify fact for other - reasons, though this is discouraged wherever possible. Also a file - may alter, and then be returned to its previous content, which would - often be indicated as two incremental alterations to the value of the - modify fact. - - For directories, this value should alter whenever a change occurs to - the directory such that different filenames would (or might) be - included in MLSD output of that directory. - - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 37] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - modify-fact = "Modify" "=" time-val - -8.5.4. The create Fact - - The create fact indicates when a file, or directory, was first - created. Exactly what "creation" is for this purpose is not - specified here, and may vary from server to server. About all that - can be said about the value returned is that it can never indicate a - later time than the modify fact. - - create-fact = "Create" "=" time-val - - Implementation Note: Implementors of this fact on UNIX(TM) systems - should note that the unix "stat" "st_ctime" field does not give - creation time, and that unix file systems do not record creation - time at all. Unix (and POSIX) implementations will normally not - include this fact. - -8.5.5. The perm Fact - - The perm fact is used to indicate access rights the current FTP user - has over the object listed. Its value is always an unordered - sequence of alphabetic characters. - - perm-fact = "Perm" "=" *pvals - pvals = "a" / "c" / "d" / "e" / "f" / - "l" / "m" / "p" / "r" / "w" - - There are ten permission indicators currently defined. Many are - meaningful only when used with a particular type of object. The - indicators are case independent, "d" and "D" are the same indicator. - - The "a" permission applies to objects of type=file, and indicates - that the APPE (append) command may be applied to the file named. - - The "c" permission applies to objects of type=dir (and type=pdir, - type=cdir). It indicates that files may be created in the directory - named. That is, that a STOU command is likely to succeed, and that - STOR and APPE commands might succeed if the file named did not - previously exist, but is to be created in the directory object that - has the "c" permission. It also indicates that the RNTO command is - likely to succeed for names in the directory. - - The "d" permission applies to all types. It indicates that the - object named may be deleted, that is, that the RMD command may be - applied to it if it is a directory, and otherwise that the DELE - command may be applied to it. - - - - -Elz & Hethmon [Expires April 2000] [Page 38] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - The "e" permission applies to the directory types. When set on an - object of type=dir, type=cdir, or type=pdir it indicates that a CWD - command naming the object should succeed, and the user should be able - to enter the directory named. For type=pdir it also indicates that - the CDUP command may succeed (if this particular pathname is the one - to which a CDUP would apply.) - - The "f" permission for objects indicates that the object named may be - renamed - that is, may be the object of an RNFR command. - - The "l" permission applies to the directory file types, and indicates - that the listing commands, LIST, NLST, and MLSD may be applied to the - directory in question. - - The "m" permission applies to directory types, and indicates that the - MKD command may be used to create a new directory within the - directory under consideration. - - The "p" permission applies to directory types, and indicates that - objects in the directory may be deleted, or (stretching naming a - little) that the directory may be purged. Note: it does not indicate - that the RMD command may be used to remove the directory named - itself, the "d" permission indicator indicates that. - - The "r" permission applies to type=file objects, and for some - systems, perhaps to other types of objects, and indicates that the - RETR command may be applied to that object. - - The "w" permission applies to type=file objects, and for some - systems, perhaps to other types of objects, and indicates that the - STOR command may be applied to the object named. - - Note: That a permission indicator is set can never imply that the - appropriate command is guaranteed to work - just that it might. - Other system specific limitations, such as limitations on - available space for storing files, may cause an operation to - fail, where the permission flags may have indicated that it was - likely to succeed. The permissions are a guide only. - - Implementation note: The permissions are described here as they apply - to FTP commands. They may not map easily into particular - permissions available on the server's operating system. Servers - are expected to synthesize these permission bits from the - permission information available from operating system. For - example, to correctly determine whether the "D" permission bit - should be set on a directory for a server running on the - UNIX(TM) operating system, the server should check that the - directory named is empty, and that the user has write permission - - - -Elz & Hethmon [Expires April 2000] [Page 39] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - on both the directory under consideration, and its parent - directory. - - Some systems may have more specific permissions than those - listed here, such systems should map those to the flags defined - as best they are able. Other systems may have only more broad - access controls. They will generally have just a few possible - permutations of permission flags, however they should attempt to - correctly represent what is permitted. - -8.5.6. The lang Fact - - The lang fact describes the natural language of the filename for use - in display purposes. Values used here should be taken from the - language registry of the IANA. See [13] for the syntax, and - procedures, related to language tags. - - lang-fact = "Lang" "=" token - - Server-FTP implementations MUST NOT guess language values. Language - values must be determined in an unambiguous way such as file system - tagging of language or by user configuration. Note that the lang - fact provides no information at all about the content of a file, only - about the encoding of its name. - -8.5.7. The size Fact - - The size fact applies to non-directory file types and should always - reflect the approximate size of the file. This should be as accurate - as the server can make it, without going to extraordinary lengths, - such as reading the entire file. The size is expressed in units of - octets of data in the file. - - Given limitations in some systems, Client-FTP implementations must - understand this size may not be precise and may change between the - time of a MLST and RETR operation. - - Clients that need highly accurate size information for some - particular reason should use the SIZE command as defined in section - 4. The most common need for this accuracy is likely to be in - conjunction with the REST command described in section 5. The size - fact, on the other hand, should be used for purposes such as - indicating to a human user the approximate size of the file to be - transferred, and perhaps to give an idea of expected transfer - completion time. - - - - - - -Elz & Hethmon [Expires April 2000] [Page 40] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - size-fact = "Size" "=" 1*DIGIT - -8.5.8. The media-type Fact - - The media-type fact represents the IANA media type of the file named, - and applies only to non-directory types. The list of values used - must follow the guidelines set by the IANA registry. - - media-type = "Media-Type" "=" <per IANA guidelines> - - Server-FTP implementations MUST NOT guess media type values. Media - type values must be determined in an unambiguous way such as file - system tagging of media-type or by user configuration. This fact - gives information about the content of the file named. Both the - primary media type, and any appropriate subtype should be given, - separated by a slash "/" as is traditional. - -8.5.9. The charset Fact - - The charset fact provides the IANA character set name, or alias, for - the encoded pathnames in a MLSx response. The default character set - is UTF-8 unless specified otherwise. FTP implementations SHOULD use - UTF-8 if possible to encourage maximum interoperability. The value - of this fact applies to the pathname only, and provides no - information about the contents of the file. - - charset-type = "Charset" "=" token - -8.5.10. Required facts - - Servers are not required to support any particular set of the - available facts. However, servers SHOULD, if conceivably possible, - support at least the type, perm, size, unique, and modify facts. - -8.6. System Dependent and Local Facts - - By using an system dependent fact, or a local fact, a server-PI may - communicate to the user-PI information about the file named which is - peculiar to the underlying file system. - -8.6.1. System Dependent Facts - - System dependent fact names are labeled by prefixing a label - identifying the specific information returned by the name of the - appropriate operating system from the IANA maintained list of - operating system names. - - - - - -Elz & Hethmon [Expires April 2000] [Page 41] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - The value of an OS dependent fact may be whatever is appropriate to - convey the information available. It must be encoded as a "token" as - defined in section 2.1 however. - - In order to allow reliable interoperation between users of system - dependent facts, the IANA will maintain a registry of system - dependent fact names, their syntax, and the interpretation to be - given to their values. Registrations of system dependent facts are - to be accomplished according to the procedures of section 11. - -8.6.2. Local Facts - - Implementations may also make available other facts of their own - choosing. As the method of interpretation of such information will - generally not be widely understood, server-PIs should be aware that - clients will typically ignore any local facts provided. As there is - no registration of locally defined facts, it is entirely possible - that different servers will use the same local fact name to provide - vastly different information. Hence user-PIs should be hesitant - about making any use of any information in a locally defined fact - without some other specific assurance that the particular fact is one - that they do comprehend. - - Local fact names all begin with the sequence "X.". The rest of the - name is a "token" (see section 2.1). The value of a local fact can - be anything at all, provided it can be encoded as a "token". - -8.7. MLSx Examples - - The following examples are all taken from dialogues between existing - FTP clients and servers. Because of this, not all possible - variations of possible response formats are shown in the examples. - This should not be taken as limiting the options of other server - implementors. Where the examples show OS dependent information, that - is to be treated as being purely for the purposes of demonstration of - some possible OS specific information that could be defined. As at - the time of the writing of this document, no OS specific facts or - file types have been defined, the examples shown here should not be - treated as in any way to be preferred over other possible similar - definitions. Consult the IANA registries to determine what types and - facts have been defined. - - In the examples shown, only relevant commands and responses have been - included. This is not to imply that other commands (including - authentication, directory modification, PORT or PASV commands, or - similar) would not be present in an actual connection, or were not, - in fact, actually used in the examples before editing. Note also - that the formats shown are those that are transmitted between client - - - -Elz & Hethmon [Expires April 2000] [Page 42] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - and server, not formats which would normally ever be reported to the - user of the client. - - In the examples, lines that begin "C> " were sent over the control - connection from the client to the server, lines that begin "S> " were - sent over the control connection from the server to the client, and - lines that begin "D> " were sent from the server to the client 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. - -8.7.1. Simple MLST - - C> PWD - S> 257 "/tmp" is current directory. - C> MLst cap60.pl198.tar.gz - S> 250- Listing cap60.pl198.tar.gz - S> Type=file;Size=1024990;Perm=r; /tmp/cap60.pl198.tar.gz - S> 250 End - - The client first asked to be told the current directory of the - server. This was purely for the purposes of clarity of this example. - The client then requested facts about a specific file. The server - returned the "250-" first control-response line, followed by a single - line of facts about the file, followed by the terminating "250 " - line. The text on the control-response line and the terminating line - can be anything the server decides to send. Notice that the fact - line is indented by a single space. Notice also that there are no - spaces in the set of facts returned, until the single space before - the filename. The filename returned on the fact line is a fully - qualified pathname of the file listed. The facts returned show that - the line refers to a file, that file contains approximately 1024990 - bytes, though more or less than that may be transferred if the file - is retrieved, and a different number may be required to store the - file at the client's file store, and the connected user has - permission to retrieve the file but not to do anything else - particularly interesting. - -8.7.2. MLST of a directory - - C> PWD - S> 257 "/" is current directory. - C> MLst tmp - S> 250- Listing tmp - S> Type=dir;Modify=19981107085215;Perm=el; /tmp - - - -Elz & Hethmon [Expires April 2000] [Page 43] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - S> 250 End - - Again the PWD is just for the purposes of demonstration for the - example. The MLST fact line this time shows that the file listed is - a directory, that it was last modified at 08:52:15 on the 7th of - November, 1998 UTC, and that the user has permission to enter the - directory, and to list its contents, but not to modify it in any way. - Again, the fully qualified path name of the directory listed is - given. - -8.7.3. MLSD of a directory - - C> MLSD tmp - S> 150 BINARY connection open for MLSD tmp - D> Type=cdir;Modify=19981107085215;Perm=el; tmp - D> Type=cdir;Modify=19981107085215;Perm=el; /tmp - D> Type=pdir;Modify=19990112030508;Perm=el; .. - D> Type=file;Size=25730;Modify=19940728095854;Perm=; capmux.tar.z - D> Type=file;Size=1830;Modify=19940916055648;Perm=r; hatch.c - D> Type=file;Size=25624;Modify=19951003165342;Perm=r; MacIP-02.txt - D> Type=file;Size=2154;Modify=19950501105033;Perm=r; uar.netbsd.patch - D> Type=file;Size=54757;Modify=19951105101754;Perm=r; iptnnladev.1.0.sit.hqx - D> Type=file;Size=226546;Modify=19970515023901;Perm=r; melbcs.tif - D> Type=file;Size=12927;Modify=19961025135602;Perm=r; tardis.1.6.sit.hqx - D> Type=file;Size=17867;Modify=19961025135602;Perm=r; timelord.1.4.sit.hqx - D> Type=file;Size=224907;Modify=19980615100045;Perm=r; uar.1.2.3.sit.hqx - D> Type=file;Size=1024990;Modify=19980130010322;Perm=r; cap60.pl198.tar.gz - S> 226 MLSD completed - - In this example notice that there is no leading space on the fact - lines returned over the data connection. Also notice that two lines - of "type=cdir" have been given. These show two alternate names for - the directory listed, one a fully qualified pathname, and the other a - local name relative to the servers current directory when the MLSD - was performed. Note that all other filenames in the output are - relative to the directory listed, though the server could, if it - chose, give a fully qualified path name for the "type=pdir" line. - This server has chosen not to. The other files listed present a - fairly boring set of files that are present in the listed directory. - Note that there is no particular order in which they are listed. - They are not sorted by filename, by size, or by modify time. Note - also that the "perm" fact has an empty value for the file - "capmux.tar.z" indicating that the connected user has no permissions - at all for that file. This server has chosen to present the "cdir" - and "pdir" lines before the lines showing the content of the - directory, it is not required to do so. The "size" fact does not - provide any meaningful information for a directory, so is not - included in the fact lines for the directory types shown. - - - -Elz & Hethmon [Expires April 2000] [Page 44] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -8.7.4. A more complex example - - C> MLst test - S> 250- Listing test - S> Type=dir;Perm=el;Unique=keVO1+ZF4 test - S> 250 End - C> MLSD test - S> 150 BINARY connection open for MLSD test - D> Type=cdir;Perm=el;Unique=keVO1+ZF4; test - D> Type=pdir;Perm=e;Unique=keVO1+d?3; .. - D> Type=OS.unix=slink:/foobar;Perm=;Unique=keVO1+4G4; foobar - D> Type=OS.unix=chr-13/29;Perm=;Unique=keVO1+5G4; device - D> Type=OS.unix=blk-11/108;Perm=;Unique=keVO1+6G4; block - D> Type=file;Perm=awr;Unique=keVO1+8G4; writable - D> Type=dir;Perm=cpmel;Unique=keVO1+7G4; promiscuous - D> Type=dir;Perm=;Unique=keVO1+1t2; no-exec - D> Type=file;Perm=r;Unique=keVO1+EG4; two words - D> Type=file;Perm=r;Unique=keVO1+IH4; leading space - D> Type=file;Perm=r;Unique=keVO1+1G4; file1 - D> Type=dir;Perm=cpmel;Unique=keVO1+7G4; incoming - D> Type=file;Perm=r;Unique=keVO1+1G4; file2 - D> Type=file;Perm=r;Unique=keVO1+1G4; file3 - D> Type=file;Perm=r;Unique=keVO1+1G4; file4 - S> 226 MLSD completed - C> MLSD test/incoming - S> 150 BINARY connection open for MLSD test/incoming - D> Type=cdir;Perm=cpmel;Unique=keVO1+7G4; test/incoming - D> Type=pdir;Perm=el;Unique=keVO1+ZF4; .. - D> Type=file;Perm=awdrf;Unique=keVO1+EH4; bar - D> Type=file;Perm=awdrf;Unique=keVO1+LH4; - D> Type=file;Perm=rf;Unique=keVO1+1G4; file5 - D> Type=file;Perm=rf;Unique=keVO1+1G4; file6 - D> Type=dir;Perm=cpmdelf;Unique=keVO1+!s2; empty - S> 226 MLSD completed - - For the purposes of this example the fact set requested has been - modified to delete the "size" and "modify" facts, and add the - "unique" fact. First, facts about a filename have been obtained via - MLST. Note that no fully qualified path name was given this time. - That was because the server was unable to determine that information. - Then having determined that the filename represents a directory, that - directory has been listed. That listing also shows no fully - qualified path name, for the same reason, thus has but a single - "type=cdir" line. This directory (which was created especially for - the purpose) contains several interesting files. There are some with - OS dependent file types, several sub-directories, and several - ordinary files. - - - - -Elz & Hethmon [Expires April 2000] [Page 45] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - Not much can be said here about the OS dependent file types, as none - of the information shown there should be treated as any more than - possibilities. It can be seen that the OS type of the server is - "unix" though, which is one of the OS types in the IANA registry of - Operating System names. - - Of the three directories listed, "no-exec" has no permission granted - to this user to access at all. From the "Unique" fact values, it can - be determined that "promiscuous" and "incoming" in fact represent the - same directory. Its permissions show that the connected user has - permission to do essentially anything other than to delete the - directory. That directory was later listed. It happens that the - directory can not be deleted because it is not empty. - - Of the normal files listed, two contain spaces in their names. The - file called " leading space" actually contains two spaces in its - name, one before the "l" and one between the "g" and the "s". The - two spaces that separate the facts from the visible part of the path - name make that clear. The file "writable" has the "a" and "w" - permission bits set, and consequently the connected user should be - able to STOR or APPE to that file. - - The other four file names, "file1", "file2", "file3", and "file4" all - represent the same underlying file, as can be seen from the values of - the "unique" facts of each. It happens that "file1" and "file2" are - Unix "hard" links, and that "file3" and "file4" are "soft" or - "symbolic" links to the first two. None of that information is - available via standard MLST facts, it is sufficient for the purposes - of FTP to note that all represent the same file, and that the same - data would be fetched no matter which of them was retrieved, and that - all would be simultaneously modified were data stored in any. - - Finally, the sub-directory "incoming" is listed. Since "promiscuous" - is the same directory there would be no point listing it as well. In - that directory, the files "file5" and "file6" represent still more - names for the "file1" file we have seen before. Notice the entry - between that for "bar" and "file5". Though it is not possible to - easily represent it in this document, that shows a file with a name - comprising exactly three spaces (" "). A client will have no - difficulty determining that name from the output presented to it - however. The directory "empty" is, as its name implies, empty, - though that is not shown here. It can, however, be deleted, as can - file "bar" and the file whose name is three spaces. All the files - that reside in this directory can be renamed. This is a consequence - of the UNIX semantics of the directory that contains them being - modifiable. - - - - - -Elz & Hethmon [Expires April 2000] [Page 46] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -8.7.5. More accurate time information - - C> MLst file1 - S> 250- Listing file1 - S> Type=file;Modify=19990929003355.237; file1 - S> 250 End - - In this example, the server-FTP is indicating that "file1" was last - modified 237 milliseconds after 00:33:55 UTC on the 29th of - September, 1999. - -8.7.6. A different server - - C> MLST - S> 250-Begin - S> type=dir;unique=AQkAAAAAAAABCAAA; / - S> 250 End. - C> MLSD . - S> 150 Opening ASCII mode data connection for MLS. - D> type=cdir;unique=AQkAAAAAAAABCAAA; / - D> type=dir;unique=AQkAAAAAAAABEAAA; bin - D> type=dir;unique=AQkAAAAAAAABGAAA; etc - D> type=dir;unique=AQkAAAAAAAAB8AwA; halflife - D> type=dir;unique=AQkAAAAAAAABoAAA; incoming - D> type=dir;unique=AQkAAAAAAAABIAAA; lib - D> type=dir;unique=AQkAAAAAAAABWAEA; linux - D> type=dir;unique=AQkAAAAAAAABKAEA; ncftpd - D> type=dir;unique=AQkAAAAAAAABGAEA; outbox - D> type=dir;unique=AQkAAAAAAAABuAAA; quake2 - D> type=dir;unique=AQkAAAAAAAABQAEA; winstuff - S> 226 Listing completed. - C> MLSD linux - S> 150 Opening ASCII mode data connection for MLS. - D> type=cdir;unique=AQkAAAAAAAABWAEA; /linux - D> type=pdir;unique=AQkAAAAAAAABCAAA; / - D> type=dir;unique=AQkAAAAAAAABeAEA; firewall - D> type=file;size=12;unique=AQkAAAAAAAACWAEA; helo_world - D> type=dir;unique=AQkAAAAAAAABYAEA; kernel - D> type=dir;unique=AQkAAAAAAAABmAEA; scripts - D> type=dir;unique=AQkAAAAAAAABkAEA; security - S> 226 Listing completed. - C> MLSD linux/kernel - S> 150 Opening ASCII mode data connection for MLS. - D> type=cdir;unique=AQkAAAAAAAABYAEA; /linux/kernel - D> type=pdir;unique=AQkAAAAAAAABWAEA; /linux - D> type=file;size=6704;unique=AQkAAAAAAAADYAEA; k.config - D> type=file;size=7269221;unique=AQkAAAAAAAACYAEA; linux-2.0.36.tar.gz - D> type=file;size=12514594;unique=AQkAAAAAAAAEYAEA; linux-2.1.130.tar.gz - - - -Elz & Hethmon [Expires April 2000] [Page 47] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - S> 226 Listing completed. - - Note that this server returns its "unique" fact value in quite a - different format. It also returns fully qualified path names for the - "pdir" entry. - -8.7.7. Some IANA files - - C> MLSD . - S> 150 BINARY connection open for MLSD . - D> Type=cdir;Modify=19990219183438; /iana/assignments - D> Type=pdir;Modify=19990112030453; .. - D> Type=dir;Modify=19990219073522; media-types - D> Type=dir;Modify=19990112033515; character-set-info - D> Type=dir;Modify=19990112033529; languages - D> Type=file;Size=44242;Modify=19990217230400; character-sets - D> Type=file;Size=1947;Modify=19990209215600; operating-system-names - S> 226 MLSD completed - C> MLSD media-types - S> 150 BINARY connection open for MLSD media-types - D> Type=cdir;Modify=19990219073522; media-types - D> Type=cdir;Modify=19990219073522; /iana/assignments/media-types - D> Type=pdir;Modify=19990219183438; .. - D> Type=dir;Modify=19990112033045; text - D> Type=dir;Modify=19990219183442; image - D> Type=dir;Modify=19990112033216; multipart - D> Type=dir;Modify=19990112033254; video - D> Type=file;Size=30249;Modify=19990218032700; media-types - S> 226 MLSD completed - C> MLSD character-set-info - S> 150 BINARY connection open for MLSD character-set-info - D> Type=cdir;Modify=19990112033515; character-set-info - D> Type=cdir;Modify=19990112033515; /iana/assignments/character-set-info - D> Type=pdir;Modify=19990219183438; .. - D> Type=file;Size=1234;Modify=19980903020400; windows-1251 - D> Type=file;Size=4557;Modify=19980922001400; tis-620 - D> Type=file;Size=801;Modify=19970324130000; ibm775 - D> Type=file;Size=552;Modify=19970320130000; ibm866 - D> Type=file;Size=922;Modify=19960505140000; windows-1258 - S> 226 MLSD completed - C> MLSD languages - S> 150 BINARY connection open for MLSD languages - D> Type=cdir;Modify=19990112033529; languages - D> Type=cdir;Modify=19990112033529; /iana/assignments/languages - D> Type=pdir;Modify=19990219183438; .. - D> Type=file;Size=2391;Modify=19980309130000; default - D> Type=file;Size=943;Modify=19980309130000; tags - D> Type=file;Size=870;Modify=19971026130000; navajo - - - -Elz & Hethmon [Expires April 2000] [Page 48] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - D> Type=file;Size=699;Modify=19950911140000; no-bok - S> 226 MLSD completed - C> PWD - S> 257 "/iana/assignments" is current directory. - - This example shows some of the IANA maintained files that are - relevant for this specification in MLSD format. Note that these - listings have been edited by deleting many entries, the actual - listings are much longer. - -8.7.8. A stress test of case (in)dependence - - The following example is intended to make clear some cases where case - dependent strings are permitted in the MLSx commands, and where case - independent strings are required. - - C> MlsD . - S> 150 BINARY connection open for MLSD . - D> Type=pdir;Modify=19990929011228;Perm=el;Unique=keVO1+ZF4; .. - D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+Bd8; FILE2 - D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+aG8; file3 - D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+ag8; FILE3 - D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+bD8; file1 - D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+bD8; file2 - D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+Ag8; File3 - D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+bD8; File1 - D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+Bd8; File2 - D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+bd8; FILE1 - S> 226 MLSD completed - - Note first that the "MLSD" command, shown here as "MlsD" is case - independent. Clients may issue this command in any case, or - combination of cases, they desire. This is the case for all FTP - commands. - - Next, notice the labels of the facts. These are also case - independent strings, Server-FTP is permitted to return them in any - case they desire. User-FTP must be prepared to deal with any case, - though it may do this by mapping the labels to a common case if - desired. - - Then, notice that there are nine objects of "type" file returned. In - a case independent NVFS these would represent three different file - names, "file1", "file2", and "file3". With a case dependent NVFS all - nine represent different file names. Either is possible, server-FTPs - may implement a case dependent or a case independent NVFS. User-FTPs - must allow for case dependent selection of files to manipulate on the - server. - - - -Elz & Hethmon [Expires April 2000] [Page 49] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - Lastly, notice that the value of the "unique" fact is case dependent. - In the example shown, "file1", "File1", and "file2" all have the same - "unique" fact value "keVO1+bD8", and thus all represent the same - underlying file. On the other hand, "FILE1" has a different "unique" - fact value ("keVO1+bd8") and hence represents a different file. - Similarly, "FILE2" and "File2" are two names for the same underlying - file, whereas "file3", "File3" and "FILE3" all represent different - underlying files. - - That the approximate sizes ("size" fact) and last modification times - ("modify" fact) are the same in all cases might be no more than a - coincidence. - - It is not suggested that the operators of server-FTPs create NVFS - which stress the protocols to this extent, however both user and - server implementations must be prepared to deal with such extreme - examples. - -8.8. FEAT response for MLSx - - When responding to the FEAT command, a server-FTP process that - supports MLST, and MLSD, plus internationalization of pathnames, MUST - indicate that this support exists. It does this by including a MLST - feature line. As well as indicating the basic support, the MLST - feature line indicates which MLST facts are available from the - server, and which of those will be returned if no subsequent "OPTS - MLST" command is sent. - - mlst-feat = SP "MLST" [SP factlist] CRLF - factlist = 1*( factname ["*"] ";" ) - - The initial space shown in the mlst-feat response is that required by - the FEAT command, two spaces are not permitted. If no factlist is - given, then the server-FTP process is indicating that it supports - MLST, but implements no facts. Only pathnames can be returned. This - would be a minimal MLST implementation, and useless for most - practical purposes. Where the factlist is present, the factnames - included indicate the facts supported by the server. Where the - optional asterisk appears after a factname, that fact will be - included in MLST format responses, until an "OPTS MLST" is given to - alter the list of facts returned. After that, subsequent FEAT - commands will return the asterisk to show the facts selected by the - most recent "OPTS MLST". - - Note that there is no distinct FEAT output for MLSD. The presence of - the MLST feature indicates that both MLST and MLSD are supported. - - - - - -Elz & Hethmon [Expires April 2000] [Page 50] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -8.8.1. Examples - - C> Feat - S> 211- Features supported - S> REST STREAM - S> MDTM - S> SIZE - S> TVFS - S> UTF8 - S> MLST Type*;Size*;Modify*;Perm*;Unique*;UNIX.mode;UNIX.chgd;X.hidden; - S> 211 End - - Aside from some features irrelevant here, this server indicates that - it supports MLST including several, but not all, standard facts, all - of which it will send by default. It also supports two OS dependent - facts, and one locally defined fact. The latter three must be - requested expressly by the client for this server to supply them. - - C> Feat - S> 211-Extensions supported: - S> CLNT - S> MDTM - S> MLST type*;size*;modify*;UNIX.mode*;UNIX.owner;UNIX.group;unique; - S> PASV - S> REST STREAM - S> SIZE - S> TVFS - S> Compliance Level: 19981201 (IETF mlst-05) - S> 211 End. - - Again, in addition to some irrelevant features here, this server - indicates that it supports MLST, four of the standard facts, one of - which ("unique") is not enabled by default, and several OS dependent - facts, one of which is provided by the server by default. This - server actually supported more OS dependent facts. Others were - deleted for the purposes of this document to comply with document - formatting restrictions. - -8.9. OPTS parameters for MLST - - For the MLSx commands, the Client-FTP may specify a list of facts it - wishes to be returned in all subsequent MLSx commands until another - OPTS MLST command is sent. The format is specified by: - - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 51] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - mlst-opts = "OPTS" SP "MLST" - [ SP 1*( factname ";" ) ] - - By sending the "OPTS MLST" command, the client requests the server to - include only the facts listed as arguments to the command in - subsequent output from MLSx commands. Facts not included in the - "OPTS MLST" command MUST NOT be returned by the server. Facts that - are included should be returned for each entry returned from the MLSx - command where they meaningfully apply. Facts requested that are not - supported, or which are inappropriate to the file or directory being - listed should simply be omitted from the MLSx output. This is not an - error. Note that where no factname arguments are present, the client - is requesting that only the file names be returned. In this case, - and in any other case where no facts are included in the result, the - space that separates the fact names and their values from the file - name is still required. That is, the first character of the output - line will be a space, (or two characters will be spaces when the line - is returned over the control connection,) and the file name will - start immediately thereafter. - - Clients should note that generating values for some facts can be - possible, but very expensive, for some servers. It is generally - acceptable to retrieve any of the facts that the server offers as its - default set before any "OPTS MLST" command has been given, however - clients should use particular caution before requesting any facts not - in that set. That is, while other facts may be available from the - server, clients should refrain from requesting such facts unless - there is a particular operational requirement for that particular - information, which ought be more significant than perhaps simply - improving the information displayed to an end user. - - Note, there is no "OPTS MLSD" command, the fact names set with the - "OPTS MLST" command apply to both MLST and MLSD commands. - - Servers are not required to accept "OPTS MLST" commands before - authentication of the user-PI, but may choose to permit them. - -8.9.1. OPTS MLST Response - - The "response-message" from [6] to a successful OPTS MLST command has - the following syntax. - - mlst-opt-resp = "MLST OPTS" [ SP 1*( factname ";" ) ] - - This defines the "response-message" as used in the "opts-good" - message in RFC2389 [6]. - - - - - -Elz & Hethmon [Expires April 2000] [Page 52] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - The facts named in the response are those which the server will now - include in MLST (and MLSD) response, after the processing of the - "OPTS MLST" command. Any facts from the request not supported by the - server will be omitted from this response message. If no facts will - be included, the list of facts will be empty. Note that the list of - facts returned will be the same as those marked by a trailing - asterisk ("*") in a subsequent FEAT command response. There is no - requirement that the order of the facts returned be the same as that - in which they were requested, or that in which they will be listed in - a FEAT command response, or that in which facts are returned in MLST - responses. The fixed string "MLST OPTS" in the response may be - returned in any case, or mixture of cases. - -8.9.2. Examples - - C> Feat - S> 211- Features supported - S> MLST Type*;Size;Modify*;Perm;Unique;UNIX.mode;UNIX.chgd;X.hidden; - S> 211 End - C> OptS Mlst Type;UNIX.mode;Perm; - S> 201 MLST OPTS Type;Perm;UNIX.mode; - C> Feat - S> 211- Features supported - S> MLST Type*;Size;Modify;Perm*;Unique;UNIX.mode*;UNIX.chgd;X.hidden; - S> 211 End - C> opts MLst lang;type;charset;create; - S> 201 MLST OPTS Type; - C> Feat - S> 211- Features supported - S> MLST Type*;Size;Modify;Perm;Unique;UNIX.mode;UNIX.chgd;X.hidden; - S> 211 End - C> OPTS mlst size;frogs; - S> 201 MLST OPTS Size; - C> Feat - S> 211- Features supported - S> MLST Type;Size*;Modify;Perm;Unique;UNIX.mode;UNIX.chgd;X.hidden; - S> 211 End - C> opts MLst unique type; - S> 501 Invalid MLST options - C> Feat - S> 211- Features supported - S> MLST Type;Size*;Modify;Perm;Unique;UNIX.mode;UNIX.chgd;X.hidden; - S> 211 End - - For the purposes of this example, features other than MLST have been - deleted from the output to avoid clutter. The example shows the - initial default feature output for MLST. The facts requested are - then changed by the client. The first change shows facts that are - - - -Elz & Hethmon [Expires April 2000] [Page 53] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - available from the server being selected. Subsequent FEAT output - shows the altered features as being returned. The client then - attempts to select some standard features which the server does not - support. This is not an error, however the server simply ignores the - requests for unsupported features, as the FEAT output that follows - shows. Then, the client attempts to request a non-standard, and - unsupported, feature. The server ignores that, and selects only the - supported features requested. Lastly, the client sends a request - containing a syntax error (spaces cannot appear in the factlist.) The - server-FTP sends an error response and completely ignores the - request, leaving the fact set selected as it had been previously. - - Note that in all cases, except the error response, the response lists - the facts that have been selected. - - C> Feat - S> 211- Features supported - S> MLST Type*;Size*;Modify*;Perm*;Unique*;UNIX.mode;UNIX.chgd;X.hidden; - S> 211 End - C> Opts MLST - S> 201 MLST OPTS - C> Feat - S> 211- Features supported - S> MLST Type;Size;Modify;Perm;Unique;UNIX.mode;UNIX.chgd;X.hidden; - S> 211 End - C> MLst tmp - S> 250- Listing tmp - S> /tmp - S> 250 End - C> OPTS mlst unique;size; - S> 201 MLST OPTS Size;Unique; - C> MLst tmp - S> 250- Listing tmp - S> Unique=keVO1+YZ5; /tmp - S> 250 End - C> OPTS mlst unique;type;modify; - S> 201 MLST OPTS Type;Modify;Unique; - C> MLst tmp - S> 250- Listing tmp - S> Type=dir;Modify=19990930152225;Unique=keVO1+YZ5; /tmp - S> 250 End - C> OPTS mlst fish;cakes; - S> 201 MLST OPTS - C> MLst tmp - S> 250- Listing tmp - S> /tmp - S> 250 End - C> OptS Mlst Modify;Unique; - - - -Elz & Hethmon [Expires April 2000] [Page 54] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - S> 201 MLST OPTS Modify;Unique; - C> MLst tmp - S> 250- Listing tmp - S> Modify=19990930152225;Unique=keVO1+YZ5; /tmp - S> 250 End - C> opts MLst fish cakes; - S> 501 Invalid MLST options - C> MLst tmp - S> 250- Listing tmp - S> Modify=19990930152225;Unique=keVO1+YZ5; /tmp - S> 250 End - - This example shows the effect of changing the facts requested upon - subsequent MLST commands. Notice that a syntax error leaves the set - of selected facts unchanged. Also notice exactly two spaces - preceding the pathname when no facts were selected, either - deliberately, or because none of the facts requested were available. - -9. Impact On Other FTP Commands - - Along with the introduction of MLST, traditional FTP commands must be - extended to allow for the use of more than US-ASCII or EBCDIC - character sets. In general, the support of MLST requires support for - arbitrary character sets wherever filenames and directory names are - allowed. This applies equally to both arguments given to the - following commands and to the replies from them, as appropriate. - - CWD - RETR - STOR - STOU - APPE - RNFR - RNTO - DELE - RMD - MKD - PWD - STAT - - The arguments to all of these commands should be processed the same - way that MLST commands and responses are processed with respect to - handling embedded spaces, CRs and NULs. See section 2.2. - - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 55] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -10. Character sets and Internationalization - - FTP commands are protocol elements, and are always expressed in - ASCII. FTP responses are composed of the numeric code, which is a - protocol element, and a message, which is often expected to convey - information to the user. It is not expected that users normally - interact directly with the protocol elements, rather the user FTP- - process constructs the commands, and interprets the results, in the - manner best suited for the particular user. Explanatory text in - responses generally has no particular meaning to the protocol. The - numeric codes provide all necessary information. Server-PIs are free - to provide the text in any language that can be adequately - represented in ASCII, or where an alternative language and - representation has been negotiated (see [7]) in that language and - representation. - - Pathnames are expected to be encoded in UTF-8 allowing essentially - any character to be represented in a pathname. Meaningful pathnames - are defined by the server NVFS. - - No restrictions at all are placed upon the contents of files - transferred using the FTP protocols. Unless the "media-type" fact is - provided in a MLSx response nor is any advice given here which would - allow determining the content type. That information is assumed to - be obtained via other means. - -11. IANA Considerations - - This specification makes use of some lists of values currently - maintained by the IANA, and creates two new lists for the IANA to - maintain. It does not add any values to any existing registries. - - The existing IANA registries used by this specification are modified - using mechanisms specified elsewhere. - -11.1. The OS specific fact registry - - A registry of OS specific fact names shall be maintained by the IANA. - The OS names for the OS portion of the fact name must be taken from - the IANA's list of registered OS names. To add a fact name to this - OS specific registry of OS specific facts, an applicant must send to - the IANA a request, in which is specified the OS name, the OS - specific fact name, a definition of the syntax of the fact value, - which must conform to the syntax of a token as given in this - document, and a specification of the semantics to be associated with - the particular fact and its values. Upon receipt of such an - application, and if the combination of OS name and OS specific fact - name has not been previously defined, the IANA will add the - - - -Elz & Hethmon [Expires April 2000] [Page 56] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - specification to the registry. - - Any examples of OS specific facts found in this document are to be - treated as examples of possible OS specific facts, and do not form a - part of the IANA's registry merely because of being included in this - document. - -11.2. The OS specific filetype registry - - A registry of OS specific file types shall be maintained by the IANA. - The OS names for the OS portion of the fact name must be taken from - the IANA's list of registered OS names. To add a file type to this - OS specific registry of OS specific file types, an applicant must - send to the IANA a request, in which is specified the OS name, the OS - specific file type, a definition of the syntax of the fact value, - which must conform to the syntax of a token as given in this - document, and a specification of the semantics to be associated with - the particular fact and its values. Upon receipt of such an - application, and if the combination of OS name and OS specific file - type has not been previously defined, the IANA will add the - specification to the registry. - - Any examples of OS specific file types found in this document are to - be treated as potential OS specific file types only, and do not form - a part of the IANA's registry merely because of being included in - this document. - -12. Security Considerations - - This memo does not directly concern security. It is not believed - that any of the mechanisms documented here impact in any particular - way upon the security of FTP. - - Implementing the SIZE command, and perhaps some of the facts of the - MDLx commands, may impose a considerable load on the server, which - could lead to denial of service attacks. Servers have, however, - implemented this for many years, without significant reported - difficulties. - - With the introduction of virtual hosts to FTP, and the possible - accompanying multiple authentication environments, server - implementors will need to take some care to ensure that integrity is - maintained. - - The FEAT and OPTS commands may be issued before the FTP - authentication has occurred [6]. This allows unauthenticated clients - to determine which of the features defined here are supported, and to - negotiate the fact list for MLSx output. No actual MLSx commands may - - - -Elz & Hethmon [Expires April 2000] [Page 57] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - be issued however, and no problems with permitting the selection of - the format prior to authentication are foreseen. - - A general discussion of issues related to the security of FTP can be - found in [14]. - -13. References - - [1] Coded Character Set--7-bit American Standard Code for Information - Interchange, ANSI X3.4-1986. - - [2] Yergeau, F., "UTF-8, a transformation format of Unicode and ISO - 10646", RFC 2044, October 1996. - - [3] Postel, J., Reynolds, J., "File Transfer Protocol (FTP)", - STD 9, RFC 959, October 1985 - - [4] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997 - - [5] Crocker, D., Overell, P., "Augmented BNF for Syntax - Specifications: ABNF", RFC 2234, November 1997 - - [6] Hethmon, P., Elz, R., "Feature negotiation mechanism for the - File Transfer Protocol", RFC 2389, August 1998 - - [7] Curtin, W., "Internationalization of the File Transfer Protocol", - RFC 2640, July 1999 - - [8] Postel, J., Reynolds, J., "Telnet protocol Specification" - STD 8, RFC 854, May 1983 - - [9] Braden, R,. "Requirements for Internet Hosts -- Application - and Support", STD 3, RFC 1123, October 1989 - - [10] Mockapetris, P., "Domain Names - Concepts and Facilities" - STD 13, RFC 1034, November 1987 - - [11] ISO/IEC 10646-1:1993 "Universal multiple-octet coded character set - (UCS) -- Part 1: Architecture and basic multilingual plane", - International Standard -- Information Technology, 1993 - - [12] Internet Assigned Numbers Authority. http://www.iana.org - Email: iana@iana.org. - - [13] Alvestrand, H., "Tags for the Identification of Languages" - RFC 1766, March 1995 - - - - -Elz & Hethmon [Expires April 2000] [Page 58] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - [14] Allman, M., Ostermann, S., "FTP Security Considerations" - RFC 2577, May 1999 - -Acknowledgments - - This document is a product of the FTPEXT working group of the IETF. - - The following people are among those who have contributed to this - document: - - Alex Belits - D. J. Bernstein - Dave Cridland - Martin J. Duerst - Mike Gleason - Mark Harris - Alun Jones - James Matthews - Luke Mewburn - Jan Mikkelsen - Keith Moore - Buz Owen - Mark Symons - Stephen Tihor - and the entire FTPEXT working group of the IETF. - - Apologies are offered to any inadvertently omitted. - - Bernhard Rosenkraenzer suggested the HOST command, and initially - described it. - - The description of the modifications to the REST command and the MDTM - and SIZE commands comes from a set of modifications suggested for - RFC959 by Rick Adams in 1989. A draft containing just those - commands, edited by David Borman, has been merged with this document. - - Mike Gleason provided access to the FTP server used in some of the - examples. - - All of the examples in this document are taken from actual - client/server exchanges, though some have been edited for brevity, or - to meet document formatting requirements. - - - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 59] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -Copyright - - This document is in the public domain. Any and all copyright - protection that might apply in any jurisdiction is expressly - disclaimed. - -Editors' Addresses - - Robert Elz - University of Melbourne - Department of Computer Science - Parkville, Vic 3052 - Australia - - Email: kre@munnari.OZ.AU - - - Paul Hethmon - Hethmon Brothers - 2305 Chukar Road - Knoxville, TN 37923 USA - - Phone: +1 423 690 8990 - Email: phethmon@hethmon.com - - - - - - - - - - - - - - - - - - - - - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 60] |
