1FTPEXT Working Group R. Elz 2Internet Draft University of Melbourne 3Expiration Date: April 2000 4 P. Hethmon 5 Hethmon Brothers 6 7 October 1999 8 9 10 Extensions to FTP 11 12 13 draft-ietf-ftpext-mlst-08.txt 14 15Status of this Memo 16 17 This document is an Internet-Draft and is NOT offered in accordance 18 with Section 10 of RFC2026, and the author does not provide the IETF 19 with any rights other than to publish as an Internet-Draft. 20 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF), its areas, and its working groups. Note that 23 other groups may also distribute working documents as Internet- 24 Drafts. 25 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 30 31 The list of current Internet-Drafts can be accessed at 32 http://www.ietf.org/ietf/1id-abstracts.txt. 33 34 To view the list Internet-Draft Shadow Directories, see 35 http://www.ietf.org/shadow.html. 36 37 This entire section has been prepended to this document automatically 38 during formatting without any direct involvement by the author(s) of 39 this draft. 40 41 42 43 44 45 46 47 48 49 50 51 52Elz & Hethmon [Expires April 2000] [Page 1] 53 54 55Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 56 57 58Abstract 59 60 In order to overcome the problems caused by the undefined format of 61 the current FTP LIST command output, a new command is needed to 62 transfer standardized listing information from Server-FTP to User- 63 FTP. Commands to enable this are defined in this document. 64 65 In order to allow consenting clients and servers to interact more 66 freely, a quite basic, and optional, virtual file store structure is 67 defined. 68 69 This proposal also extends the FTP protocol to allow character sets 70 other than US-ASCII[1] by allowing the transmission of 8-bit 71 characters and the recommended use of UTF-8[2] encoding. 72 73 Much implemented, but long undocumented, mechanisms to permit 74 restarts of interrupted data transfers in STREAM mode, are also 75 included here. 76 77 Lastly, the HOST command has been added to allow a style of "virtual 78 site" to be constructed. 79 80 Changed in this version of this document: Minor corrections as 81 discussed on the mailing list, including fixing many typographical 82 errors; Additional examples. This paragraph will be deleted from the 83 final version of this document. 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109Elz & Hethmon [Expires April 2000] [Page 2] 110 111 112Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 113 114 115 116 117Table of Contents 118 119 Abstract ................................................ 2 120 1 Introduction ............................................ 4 121 2 Document Conventions .................................... 4 122 2.1 Basic Tokens ............................................ 5 123 2.2 Pathnames ............................................... 5 124 2.3 Times ................................................... 7 125 2.4 Server Replies .......................................... 8 126 3 File Modification Time (MDTM) ........................... 8 127 3.1 Syntax .................................................. 9 128 3.2 Error responses ......................................... 9 129 3.3 FEAT response for MDTM .................................. 9 130 3.4 MDTM Examples ........................................... 10 131 4 File SIZE ............................................... 11 132 4.1 Syntax .................................................. 11 133 4.2 Error responses ......................................... 11 134 4.3 FEAT response for SIZE .................................. 12 135 4.4 Size Examples ........................................... 12 136 5 Restart of Interrupted Transfer (REST) .................. 13 137 5.1 Restarting in STREAM Mode ............................... 13 138 5.2 Error Recovery and Restart .............................. 14 139 5.3 Syntax .................................................. 14 140 5.4 FEAT response for REST .................................. 16 141 5.5 REST Example ............................................ 16 142 6 Virtual FTP servers ..................................... 16 143 6.1 The HOST command ........................................ 18 144 6.2 Syntax of the HOST command .............................. 18 145 6.3 HOST command semantics .................................. 19 146 6.4 HOST command errors ..................................... 21 147 6.5 FEAT response for HOST command .......................... 22 148 7 A Trivial Virtual File Store (TVFS) ..................... 23 149 7.1 TVFS File Names ......................................... 23 150 7.2 TVFS Path Names ......................................... 24 151 7.3 FEAT Response for TVFS .................................. 25 152 7.4 OPTS for TVFS ........................................... 26 153 7.5 TVFS Examples ........................................... 26 154 8 Listings for Machine Processing (MLST and MLSD) ......... 28 155 8.1 Format of MLSx Requests ................................. 29 156 8.2 Format of MLSx Response ................................. 29 157 8.3 Filename encoding ....................................... 32 158 8.4 Format of Facts ......................................... 33 159 8.5 Standard Facts .......................................... 33 160 8.6 System Dependent and Local Facts ........................ 41 161 8.7 MLSx Examples ........................................... 42 162 8.8 FEAT response for MLSx .................................. 50 163 164 165 166Elz & Hethmon [Expires April 2000] [Page 3] 167 168 169Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 170 171 172 8.9 OPTS parameters for MLST ................................ 51 173 9 Impact On Other FTP Commands ............................ 55 174 10 Character sets and Internationalization ................. 56 175 11 IANA Considerations ..................................... 56 176 11.1 The OS specific fact registry ........................... 56 177 11.2 The OS specific filetype registry ....................... 57 178 12 Security Considerations ................................. 57 179 13 References .............................................. 58 180 Acknowledgments ......................................... 59 181 Copyright ............................................... 60 182 Editors' Addresses ...................................... 60 183 184 185 186 1871. Introduction 188 189 This document amends the File Transfer Protocol (FTP) [3]. Five new 190 commands are added: "SIZE", "HOST", "MDTM", "MLST", and "MLSD". The 191 existing command "REST" is modified. Of those, the "SIZE" and "MDTM" 192 commands, and the modifications to "REST" have been in wide use for 193 many years. The others are new. 194 195 These commands allow a client to restart an interrupted transfer in 196 transfer modes not previously supported in any documented way, to 197 support the notion of virtual hosts, and to obtain a directory 198 listing in a machine friendly, predictable, format. 199 200 An optional structure for the server's file store (NVFS) is also 201 defined, allowing servers that support such a structure to convey 202 that information to clients in a standard way, thus allowing clients 203 more certainty in constructing and interpreting path names. 204 2052. Document Conventions 206 207 This document makes use of the document conventions defined in BCP14 208 [4]. That provides the interpretation of capitalized imperative 209 words like MUST, SHOULD, etc. 210 211 This document also uses notation defined in STD 9 [3]. In 212 particular, the terms "reply", "user", "NVFS", "file", "pathname", 213 "FTP commands", "DTP", "user-FTP process", "user-PI", "user-DTP", 214 "server-FTP process", "server-PI", "server-DTP", "mode", "type", 215 "NVT", "control connection", "data connection", and "ASCII", are all 216 used here as defined there. 217 218 Syntax required is defined using the Augmented BNF defined in [5]. 219 Some general ABNF definitions are required throughout the document, 220 221 222 223Elz & Hethmon [Expires April 2000] [Page 4] 224 225 226Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 227 228 229 those will be defined later in this section. At first reading, it 230 may be wise to simply recall that these definitions exist here, and 231 skip to the next section. 232 2332.1. Basic Tokens 234 235 This document imports the core definitions given in Appendix A of 236 [5]. There definitions will be found for basic ABNF elements like 237 ALPHA, DIGIT, SP, etc. To that, the following terms are added for 238 use in this document. 239 240 TCHAR = VCHAR / SP / HTAB ; visible plus white space 241 RCHAR = ALPHA / DIGIT / "," / "." / ":" / "!" / 242 "@" / "#" / "$" / "%" / "^" / 243 "&" / "(" / ")" / "-" / "_" / 244 "+" / "?" / "/" / "\" / "'" / 245 DQUOTE ; <"> -- double quote character (%x22) 246 247 The VCHAR (from [5]), TCHAR, and RCHAR types give basic character 248 types from varying sub-sets of the ASCII character set for use in 249 various commands and responses. 250 251 token = 1*RCHAR 252 253 A "token" is a string whose precise meaning depends upon the context 254 in which it is used. In some cases it will be a value from a set of 255 possible values maintained elsewhere. In others it might be a string 256 invented by one party to an FTP conversation from whatever sources it 257 finds relevant. 258 259 Note that in ABNF, string literals are case insensitive. That 260 convention is preserved in this document, and implies that FTP 261 commands added by this specification have names that can be 262 represented in any case. That is, "MDTM" is the same as "mdtm", 263 "Mdtm" and "MdTm" etc. However note that ALPHA, in particular, is 264 case sensitive. That implies that a "token" is a case sensitive 265 value. That implication is correct. 266 2672.2. Pathnames 268 269 Various FTP commands take pathnames as arguments, or return pathnames 270 in responses. When the MLST command is supported, as indicated in 271 the response to the FEAT command [6], pathnames are to be transferred 272 in one of the following two formats. 273 274 275 276 277 278 279 280Elz & Hethmon [Expires April 2000] [Page 5] 281 282 283Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 284 285 286 pathname = utf-8-name / raw 287 utf-8-name = <a UTF-8 encoded Unicode string> 288 raw = <any string not being a valid UTF-8 encoding> 289 290 Which format is used is at the option of the user-PI or server-PI 291 sending the pathname. UTF-8 encodings [2] contain enough internal 292 structure that it is always, in practice, possible to determine 293 whether a UTF-8 or raw encoding has been used, in those cases where 294 it matters. While it is useful for the user-PI to be able to 295 correctly display a pathname received from the server-PI to the user, 296 it is far more important for the user-PI to be able to retain and 297 retransmit the identical pathname when required. Implementations are 298 advised against converting a UTF-8 pathname to a local encoding, and 299 then attempting to invert the encoding later. Note that ASCII is a 300 subset of UTF-8. 301 302 Unless otherwise specified, the pathname is terminated by the CRLF 303 that terminates the FTP command, or by the CRLF that ends a reply. 304 Any trailing spaces preceding that CRLF form part of the name. 305 Exactly one space will precede the pathname and serve as a separator 306 from the preceding syntax element. Any additional spaces form part 307 of the pathname. See [7] for a fuller explanation of the character 308 encoding issues. All implementations supporting MLST MUST support 309 [7]. 310 311 Implementations should also beware that the control connection uses 312 Telnet NVT conventions [8], and that the Telnet IAC character, if 313 part of a pathname sent over the control connection, MUST be 314 correctly escaped as defined by the Telnet protocol. 315 316 Implementors should also be aware that although Telnet NVT 317 conventions are used over the control connections, Telnet option 318 negotiation MUST NOT be attempted. See section 4.1.2.12 of [9]. 319 3202.2.1. Pathname Syntax 321 322 Except where TVFS is supported (see section 7) this specification 323 imposes no syntax upon pathnames. Nor does it restrict the character 324 set from which pathnames are created. This does not imply that the 325 NVFS is required to make sense of all possible pathnames. Server-PIs 326 may restrict the syntax of valid pathnames in their NVFS in any 327 manner appropriate to their implementation or underlying file system. 328 Similarly, a server-PI may parse the pathname, and assign meaning to 329 the components detected. 330 331 332 333 334 335 336 337Elz & Hethmon [Expires April 2000] [Page 6] 338 339 340Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 341 342 3432.2.2. Wildcarding 344 345 For the commands defined in this specification, all pathnames are to 346 be treated literally. That is, for a pathname given as a parameter 347 to a command, the file whose name is identical to the pathname given 348 is implied. No characters from the pathname may be treated as 349 special or "magic", thus no pattern matching (other than for exact 350 equality) between the pathname given and the files present in the 351 NVFS of the Server-FTP is permitted. 352 353 Clients that desire some form of pattern matching functionality must 354 obtain a listing of the relevant directory, or directories, and 355 implement their own filename selection procedures. 356 3572.3. Times 358 359 The syntax of a time value is: 360 361 time-val = 14DIGIT [ "." 1*DIGIT ] 362 363 The leading, mandatory, fourteen digits are to be interpreted as, in 364 order from the leftmost, four digits giving the year, with a range of 365 1000-9999, two digits giving the month of the year, with a range of 366 01-12, two digits giving the day of the month, with a range of 01-31, 367 two digits giving the hour of the day, with a range of 00-23, two 368 digits giving minutes past the hour, with a range of 00-59, and 369 finally, two digits giving seconds past the minute, with a range of 370 00-60 (with 60 being used only at a leap second). Years in the tenth 371 century, and earlier, cannot be expressed. This is not considered a 372 serious defect of the protocol. 373 374 The optional digits, which are preceded by a period, give decimal 375 fractions of a second. These may be given to whatever precision is 376 appropriate to the circumstance, however implementations MUST NOT add 377 precision to time-vals where that precision does not exist in the 378 underlying value being transmitted. 379 380 Symbolically, a time-val may be viewed as 381 382 YYYYMMDDHHMMSS.sss 383 384 The "." and subsequent digits ("sss") are optional. However the "." 385 MUST NOT appear unless at least one following digit also appears. 386 387 Time values are always represented in UTC (GMT), and in the Gregorian 388 calendar regardless of what calendar may have been in use at the date 389 and time indicated at the location of the server-PI. 390 391 392 393 394Elz & Hethmon [Expires April 2000] [Page 7] 395 396 397Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 398 399 400 The technical differences between GMT, TAI, UTC, UT1, UT2, etc, are 401 not considered here. A server-FTP process should always use the same 402 time reference, so the times it returns will be consistent. Clients 403 are not expected to be time synchronized with the server, so the 404 possible difference in times that might be reported by the different 405 time standards is not considered important. 406 4072.4. Server Replies 408 409 Section 4.2 of [3] defines the format and meaning of replies by the 410 server-PI to FTP commands from the user-PI. Those reply conventions 411 are used here without change. 412 413 error-response = error-code SP *TCHAR CRLF 414 error-code = ("4" / "5") 2DIGIT 415 416 Implementors should note that the ABNF syntax (which was not used in 417 [3]) used in this document, and other FTP related documents, 418 sometimes shows replies using the one line format. Unless otherwise 419 explicitly stated, that is not intended to imply that multi-line 420 responses are not permitted. Implementors should assume that, unless 421 stated to the contrary, any reply to any FTP command (including QUIT) 422 may be of the multi-line format described in [3]. 423 424 Throughout this document, replies will be identified by the three 425 digit code that is their first element. Thus the term "500 reply" 426 means a reply from the server-PI using the three digit code "500". 427 4283. File Modification Time (MDTM) 429 430 The FTP command, MODIFICATION TIME (MDTM), can be used to determine 431 when a file in the server NVFS was last modified. This command has 432 existed in many FTP servers for many years, as an adjunct to the REST 433 command for STREAM mode, thus is widely available. However, where 434 supported, the "modify" fact which can be provided in the result from 435 the new MLST command is recommended as a superior alternative. 436 437 When attempting to restart a RETRieve, if the User-FTP makes use of 438 the MDTM command, or "modify" fact, it can check and see if the 439 modification time of the source file is more recent than the 440 modification time of the partially transferred file. If it is, then 441 most likely the source file has changed and it would be unsafe to 442 restart the previously incomplete file transfer. 443 444 When attempting to restart a STORe, the User FTP can use the MDTM 445 command to discover the modification time of the partially 446 transferred file. If it is older than the modification time of the 447 file that is about to be STORed, then most likely the source file has 448 449 450 451Elz & Hethmon [Expires April 2000] [Page 8] 452 453 454Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 455 456 457 changed and it would be unsafe to restart the file transfer. 458 459 Note that using MLST (described below) where available, can provide 460 this information, and much more, thus giving an even better 461 indication that a file has changed, and that restarting a transfer 462 would not give valid results. 463 464 Note that this is applicable to any RESTart attempt, regardless of 465 the mode of the file transfer. 466 4673.1. Syntax 468 469 The syntax for the MDTM command is: 470 471 mdtm = "MdTm" SP pathname CRLF 472 473 As with all FTP commands, the "MDTM" command label is interpreted in 474 a case insensitive manner. 475 476 The "pathname" specifies an object in the NVFS which may be the 477 object of a RETR command. Attempts to query the modification time of 478 files that are unable to be retrieved generate undefined responses. 479 480 The server-PI will respond to the MDTM command with a 213 reply 481 giving the last modification time of the file whose pathname was 482 supplied, or a 550 reply if the file does not exist, the modification 483 time is unavailable, or some other error has occurred. 484 485 mdtm-response = "213" SP time-val CRLF / 486 error-response 487 4883.2. Error responses 489 490 Where the command is correctly parsed, but the modification time is 491 not available, either because the pathname identifies no existing 492 entity, or because the information is not available for the entity 493 named, then a 550 reply should be sent. Where the command cannot be 494 correctly parsed, a 500 or 501 reply should be sent, as specified in 495 [3]. 496 4973.3. FEAT response for MDTM 498 499 When replying to the FEAT command [6], an FTP server process that 500 supports the MDTM command MUST include a line containing the single 501 word "MDTM". This MAY be sent in upper or lower case, or a mixture 502 of both (it is case insensitive) but SHOULD be transmitted in upper 503 case only. That is, the response SHOULD be 504 505 506 507 508Elz & Hethmon [Expires April 2000] [Page 9] 509 510 511Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 512 513 514 C> Feat 515 S> 211- <any descriptive text> 516 S> ... 517 S> MDTM 518 S> ... 519 S> 211 End 520 521 The ellipses indicate place holders where other features may be 522 included, and are not required. The one space indentation of the 523 feature lines is mandatory [6]. 524 5253.4. MDTM Examples 526 527 If we assume the existence of three files, A B and C, and a directory 528 D, and no other files at all, then the MTDM command may behave as 529 indicated. The "C>" lines are commands from user-PI to server-PI, 530 the "S>" lines are server-PI replies. 531 532 C> MDTM A 533 S> 213 19980615100045.014 534 C> MDTM B 535 S> 213 19980615100045.014 536 C> MDTM C 537 S> 213 19980705132316 538 C> MDTM D 539 S> 550 D is not retrievable 540 C> MDTM E 541 S> 550 No file named "E" 542 C> mdtm file6 543 S> 213 19990929003355 544 C> MdTm 19990929043300 File6 545 S> 213 19991005213102 546 C> MdTm 19990929043300 file6 547 S> 550 19990929043300 file6: No such file or directory. 548 549 From that we can conclude that both A and B were last modified at the 550 same time (to the nearest millisecond), and that C was modified 21 551 days and several hours later. 552 553 The times are in GMT, so file A was modified on the 15th of June, 554 1998, at approximately 11am in London (summer time was then in 555 effect), or perhaps at 8pm in Melbourne, Australia, or at 6am in New 556 York. All of those represent the same absolute time of course. The 557 location where the file was modified, and consequently the local wall 558 clock time at that location, is not available. 559 560 There is no file named "E" in the current directory, but there are 561 files named both "file6" and "19990929043300 File6". The 562 563 564 565Elz & Hethmon [Expires April 2000] [Page 10] 566 567 568Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 569 570 571 modification times of those files were obtained. There is no file 572 named "19990929043300 file6". 573 5744. File SIZE 575 576 The FTP command, SIZE OF FILE (SIZE), is used to obtain the transfer 577 size of a file from the server-FTP process. That is, the exact 578 number of octets (8 bit bytes) which would be transmitted over the 579 data connection should that file be transmitted. This value will 580 change depending on the current STRUcture, MODE and TYPE of the data 581 connection, or a data connection which would be created were one 582 created now. Thus, the result of the SIZE command is dependent on 583 the currently established STRU, MODE and TYPE parameters. 584 585 The SIZE command returns how many octets would be transferred if the 586 file were to be transferred using the current transfer structure, 587 mode and type. This command is normally used in conjunction with the 588 RESTART (REST) command. The server-PI might need to read the 589 partially transferred file, do any appropriate conversion, and count 590 the number of octets that would be generated when sending the file in 591 order to correctly respond to this command. Estimates of the file 592 transfer size MUST NOT be returned, only precise information is 593 acceptable. 594 5954.1. Syntax 596 597 The syntax of the SIZE command is: 598 599 size = "Size" SP pathname CRLF 600 601 The server-PI will respond to the SIZE command with a 213 reply 602 giving the transfer size of the file whose pathname was supplied, or 603 an error response if the file does not exist, the size is 604 unavailable, or some other error has occurred. The value returned is 605 in a format suitable for use with the RESTART (REST) command for mode 606 STREAM, provided the transfer mode and type are not altered. 607 608 size-response = "213" SP 1*DIGIT CRLF / 609 error-response 610 6114.2. Error responses 612 613 Where the command is correctly parsed, but the size is not available, 614 either because the pathname identifies no existing entity, or because 615 the entity named cannot be transferred in the current MODE and TYPE 616 (or at all), then a 550 reply should be sent. Where the command 617 cannot be correctly parsed, a 500 or 501 reply should be sent, as 618 specified in [3]. 619 620 621 622Elz & Hethmon [Expires April 2000] [Page 11] 623 624 625Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 626 627 6284.3. FEAT response for SIZE 629 630 When replying to the FEAT command [6], an FTP server process that 631 supports the SIZE command MUST include a line containing the single 632 word "SIZE". This word is case insensitive, and MAY be sent in any 633 mixture of upper or lower case, however it SHOULD be sent in upper 634 case. That is, the response SHOULD be 635 636 C> FEAT 637 S> 211- <any descriptive text> 638 S> ... 639 S> SIZE 640 S> ... 641 S> 211 END 642 643 The ellipses indicate place holders where other features may be 644 included, and are not required. The one space indentation of the 645 feature lines is mandatory [6]. 646 6474.4. Size Examples 648 649 Consider a text file "Example" stored on a Unix(TM) server where each 650 end of line is represented by a single octet. Assume the file 651 contains 112 lines, and 1830 octets total. Then the SIZE command 652 would produce: 653 654 C> TYPE I 655 S> 200 Type set to I. 656 C> size Example 657 S> 213 1830 658 C> TYPE A 659 S> 200 Type set to A. 660 C> Size Example 661 S> 213 1942 662 663 Notice that with TYPE=A the SIZE command reports an extra 112 octets. 664 Those are the extra octets that need to be inserted, one at the end 665 of each line, to provide correct end of line semantics for a transfer 666 using TYPE=A. Other systems might need to make other changes to the 667 transfer format of files when converting between TYPEs and MODEs. 668 The SIZE command takes all of that into account. 669 670 Since calculating the size of a file with this degree of precision 671 may take considerable effort on the part of the server-PI, user-PIs 672 should not used this command unless this precision is essential (such 673 as when about to restart an interrupted transfer). For other uses, 674 the "Size" fact of the MLST command (see section 8.5.7) ought be 675 requested. 676 677 678 679Elz & Hethmon [Expires April 2000] [Page 12] 680 681 682Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 683 684 6855. Restart of Interrupted Transfer (REST) 686 687 To avoid having to resend the entire file if the file is only 688 partially transferred, both sides need some way to be able to agree 689 on where in the data stream to restart the data transfer. 690 691 The FTP specification [3] includes three modes of data transfer, 692 Stream, Block and Compressed. In Block and Compressed modes, the 693 data stream that is transferred over the data connection is 694 formatted, allowing the embedding of restart markers into the stream. 695 The sending DTP can include a restart marker with whatever 696 information it needs to be able to restart a file transfer at that 697 point. The receiving DTP can keep a list of these restart markers, 698 and correlate them with how the file is being saved. To restart the 699 file transfer, the receiver just sends back that last restart marker, 700 and both sides know how to resume the data transfer. Note that there 701 are some flaws in the description of the restart mechanism in RFC 959 702 [3]. See section 4.1.3.4 of RFC 1123 [9] for the corrections. 703 7045.1. Restarting in STREAM Mode 705 706 In Stream mode, the data connection contains just a stream of 707 unformatted octets of data. Explicit restart markers thus cannot be 708 inserted into the data stream, they would be indistinguishable from 709 data. For this reason, the FTP specification [3] did not provide the 710 ability to do restarts in stream mode. However, there is not really 711 a need to have explicit restart markers in this case, as restart 712 markers can be implied by the octet offset into the data stream. 713 714 Because the data stream defines the file in STREAM mode, a different 715 data stream would represent a different file. Thus, an offset will 716 always represent the same position within a file. On the other hand, 717 in other modes than STREAM, the same file can be transferred using 718 quite different octet sequences, and yet be reconstructed into the 719 one identical file. Thus an offset into the data stream in transfer 720 modes other than STREAM would not give an unambiguous restart point. 721 722 If the data representation TYPE is IMAGE, and the STRUcture is File, 723 for many systems the file will be stored exactly in the same format 724 as it is sent across the data connection. It is then usually very 725 easy for the receiver to determine how much data was previously 726 received, and notify the sender of the offset where the transfer 727 should be restarted. In other representation types and structures 728 more effort will be required, but it remains always possible to 729 determine the offset with finite, but perhaps non-negligible, effort. 730 In the worst case an FTP process may need to open a data connection 731 to itself, set the appropriate transfer type and structure, and 732 actually transmit the file, counting the transmitted octets. 733 734 735 736Elz & Hethmon [Expires April 2000] [Page 13] 737 738 739Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 740 741 742 If the user-FTP process is intending to restart a retrieve, it will 743 directly calculate the restart marker, and send that information in 744 the RESTart command. However, if the user-FTP process is intending 745 to restart sending the file, it needs to be able to determine how 746 much data was previously sent, and correctly received and saved. A 747 new FTP command is needed to get this information. This is the 748 purpose of the SIZE command, as documented in section 4. 749 7505.2. Error Recovery and Restart 751 752 STREAM MODE transfers with FILE STRUcture may be restarted even 753 though no restart marker has been transferred in addition to the data 754 itself. This is done by using the SIZE command, if needed, in 755 combination with the RESTART (REST) command, and one of the standard 756 file transfer commands. 757 758 When using TYPE ASCII or IMAGE, the SIZE command will return the 759 number of octets that would actually be transferred if the file were 760 to be sent between the two systems. I.e. with type IMAGE, the SIZE 761 normally would be the number of octets in the file. With type ASCII, 762 the SIZE would be the number of octets in the file including any 763 modifications required to satisfy the TYPE ASCII CR-LF end of line 764 convention. 765 7665.3. Syntax 767 768 The syntax for the REST command when the current transfer mode is 769 STREAM is: 770 771 rest = "Rest" SP 1*DIGIT CRLF 772 773 The numeric value gives the number of octets of the immediately 774 following transfer to not actually send, effectively causing the 775 transmission to be restarted at a later point. A value of zero 776 effectively disables restart, causing the entire file to be 777 transmitted. The server-PI will respond to the REST command with a 778 350 reply, indicating that the REST parameter has been saved, and 779 that another command, which should be either RETR or STOR, should 780 then follow to complete the restart. 781 782 rest-response = "350" SP *TCHAR CRLF / 783 error-response 784 785 Server-FTP processes may permit transfer commands other than RETR and 786 STOR, such as APPE and STOU, to complete a restart, however, this is 787 not recommended. STOU (store unique) is undefined in this usage, as 788 storing the remainder of a file into a unique filename is rarely 789 going to be useful. If APPE (append) is permitted, it MUST act 790 791 792 793Elz & Hethmon [Expires April 2000] [Page 14] 794 795 796Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 797 798 799 identically to STOR when a restart marker has been set. That is, in 800 both cases, octets from the data connection are placed into the file 801 at the location indicated by the restart marker value. 802 803 The REST command is intended to complete a failed transfer. Use with 804 RETR is comparatively well defined in all cases, as the client bears 805 the responsibility of merging the retrieved data with the partially 806 retrieved file. If it chooses to use the data obtained other than to 807 complete an earlier transfer, or if it chooses to re-retrieve data 808 that had been retrieved before, that is its choice. With STOR, 809 however, the server must insert the data into the file named. The 810 results are undefined if a client uses REST to do other than restart 811 to complete a transfer of a file which had previously failed to 812 completely transfer. In particular, if the restart marker set with a 813 REST command is not at the end of the data currently stored at the 814 server, as reported by the server, or if insufficient data are 815 provided in a STOR that follows a REST to extend the destination file 816 to at least its previous size, then the effects are undefined. 817 818 The REST command must be the last command issued before the data 819 transfer command which is to cause a restarted rather than complete 820 file transfer. The effect of issuing a REST command at any other 821 time is undefined. The server-PI may react to a badly positioned 822 REST command by issuing an error response to the following command, 823 not being a restartable data transfer command, or it may save the 824 restart value and apply it to the next data transfer command, or it 825 may silently ignore the inappropriate restart attempt. Because of 826 this, a user-PI that has issued a REST command, but which has not 827 successfully transmitted the following data transfer command for any 828 reason, should send another REST command before the next data 829 transfer command. If that transfer is not to be restarted, then 830 "REST 0" should be issued. 831 832 An error-response will follow a REST command only when the server 833 does not implement the command, or the restart marker value is 834 syntactically invalid for the current transfer mode. That is, in 835 STREAM mode, if something other than one or more digits appears in 836 the parameter to the REST command. Any other errors, including such 837 problems as restart marker out of range, should be reported when the 838 following transfer command is issued. Such errors will cause that 839 transfer request to be rejected with an error indicating the invalid 840 restart attempt. 841 842 843 844 845 846 847 848 849 850Elz & Hethmon [Expires April 2000] [Page 15] 851 852 853Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 854 855 8565.4. FEAT response for REST 857 858 Where a server-FTP process supports RESTart in STREAM mode, as 859 specified here, it MUST include in the response to the FEAT command 860 [6], a line containing exactly the string "REST STREAM". This string 861 is not case sensitive, but SHOULD be transmitted in upper case. 862 Where REST is not supported at all, or supported only in block or 863 compressed modes, the REST line MUST NOT be included in the FEAT 864 response. Where required, the response SHOULD be 865 866 C> feat 867 S> 211- <any descriptive text> 868 S> ... 869 S> REST STREAM 870 S> ... 871 S> 211 end 872 873 The ellipses indicate place holders where other features may be 874 included, and are not required. The one space indentation of the 875 feature lines is mandatory [6]. 876 8775.5. REST Example 878 879 Assume that the transfer of a largish file has previously been 880 interrupted after 802816 octets had been received, that the previous 881 transfer was with TYPE=I, and that it has been verified that the file 882 on the server has not since changed. 883 884 C> TYPE I 885 S> 200 Type set to I. 886 C> PORT 127,0,0,1,15,107 887 S> 200 PORT command successful. 888 C> REST 802816 889 S> 350 Restarting at 802816. Send STORE or RETRIEVE 890 C> RETR cap60.pl198.tar 891 S> 150 Opening BINARY mode data connection 892 [...] 893 S> 226 Transfer complete. 894 8956. Virtual FTP servers 896 897 It has become common in the Internet for many domain names to be 898 allocated to a single IP address. This has introduced the concept of 899 a "virtual host", where a host appears to exist as an independent 900 entity, but in reality shares all of its resources with one, or more, 901 other such hosts. 902 903 904 905 906 907Elz & Hethmon [Expires April 2000] [Page 16] 908 909 910Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 911 912 913 Such an arrangement presents some problems for FTP Servers, as all 914 the FTP Server can detect is an incoming FTP connection to a 915 particular IP address. That is, all domain names which share the IP 916 address also share the FTP server, and more importantly, its NVFS. 917 This means that the various virtual hosts cannot offer different 918 virtual file systems to clients, nor can they offer different 919 authentication systems. 920 921 No scheme can overcome this without modifications of some kind to the 922 user-PI and the user-FTP process. That process is the only entity 923 that knows which virtual host is required. It has performed the 924 domain name to IP address translation, and thus has the original 925 domain name available. 926 927 One method which could be used to allow a style of virtual host would 928 be for the client to simply send a "CWD" command after connecting, 929 using the virtual host name as the argument to the CWD command. This 930 would allow the server-FTP process to implement the file stores of 931 the virtual hosts as sub-directories in its NVFS. This is simple, 932 and supported by essentially all server-FTP implementations without 933 requiring any code changes. 934 935 While that method is simple to describe, and to implement, it suffers 936 from several drawbacks. First, the "CWD" command is available only 937 after the user-PI has authenticated itself to the server-FTP process. 938 Thus, all virtual hosts would be required to share a common 939 authentication scheme. Second, either the server-FTP process needs 940 to be modified to understand the special nature of this first CWD 941 command, negating most of the advantage of this scheme, or all users 942 must see the same identical NVFS view upon connecting (they must 943 connect in the same initial directory) or the NVFS must implement the 944 full set of virtual host directories at each possible initial 945 directory for any possible user, or the virtual host will not be 946 truly transparent. Third, and again unless the server is specially 947 modified, a user connecting this way to a virtual host would be able 948 to trivially move to any other virtual host supported at the same 949 server-FTP process, exposing the nature of the virtual host. 950 951 Other schemes overloading other existing FTP commands have also been 952 proposed. None of those have sufficient merit to be worth 953 discussion. 954 955 The conclusion from the examination of the possibilities seems to be 956 that to obtain an adequate emulation of "real" FTP servers, server 957 modifications to support virtual hosts are required. A new command 958 seems most likely to provide the support required. 959 960 961 962 963 964Elz & Hethmon [Expires April 2000] [Page 17] 965 966 967Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 968 969 9706.1. The HOST command 971 972 A new command "HOST" is added to the FTP command set to allow 973 server-FTP process to determine to which of possibly many virtual 974 hosts the client wishes to connect. This command is intended to be 975 issued before the user is authenticated, allowing the authentication 976 scheme, and set of legal users, to be dependent upon the virtual host 977 chosen. Server-FTP processes may, if they desire, permit the HOST 978 command to be issued after the user has been authenticated, or may 979 treat that as an erroneous sequence of commands. The behavior of the 980 server-FTP process which does allow late HOST commands is undefined. 981 One reasonable interpretation would be for the user-PI to be returned 982 to the state that existed after the TCP connection was first 983 established, before user authentication. 984 985 Servers should note that the response to the HOST command is a 986 sensible time to send their "welcome" message. This allows the 987 message to be personalized for any virtual hosts that are supported, 988 and also allows the client to have determined supported languages, or 989 representations, for the message, and other messages, via the FEAT 990 response, and selected an appropriate one via the LANG command. See 991 [7] for more information. 992 9936.2. Syntax of the HOST command 994 995 The HOST command is defined as follows. 996 997 host-command = "Host" SP hostname CRLF 998 hostname = 1*DNCHAR 1*( "." 1*DNCHAR ) [ "." ] 999 DNCHAR = ALPHA / DIGIT / "-" / "_" / "$" / 1000 "!" / "%" / "[" / "]" / ":" 1001 host-response = host-ok / error-response 1002 host-ok = "220" [ SP *TCHAR ] CRLF 1003 1004 As with all FTP commands, the "host" command word is case 1005 independent, and may be specified in any character case desired. 1006 1007 The "hostname" given as a parameter specifies the virtual host to 1008 which access is desired. It should normally be the same name that 1009 was used to obtain the IP address to which the FTP control connection 1010 was made, after any client conversions to convert an abbreviated or 1011 local alias to a complete (fully qualified) domain name, but before 1012 resolving a DNS alias (owner of a CNAME resource record) to its 1013 canonical name. 1014 1015 If the client was given a network literal address, and consequently 1016 was not required to derive it from a hostname, it should send the 1017 HOST command with the network address, as specified to it, enclosed 1018 1019 1020 1021Elz & Hethmon [Expires April 2000] [Page 18] 1022 1023 1024Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 1025 1026 1027 in brackets (after eliminating any syntax, which might also be 1028 brackets, but is not required to be, from which the server deduced 1029 that a literal address had been specified.) That is, for example 1030 1031 HOST [10.1.2.3] 1032 1033 should be sent if the client had been instructed to connect to 1034 "10.1.2.3", or "[10.1.2.3]", or perhaps even IPv4:10.1.2.3. The 1035 method of indicating to a client that a literal address is to be used 1036 is beyond the scope of this specification. 1037 1038 The parameter is otherwise to be treated as a "complete domain name", 1039 as that term is defined in section 3.1 of RFC 1034 [10]. That 1040 implies that the name is to be treated as a case independent string, 1041 in that upper case ASCII characters are to be treated as equivalent 1042 to the corresponding lower case ASCII characters, but otherwise 1043 preserved as given. It also implies some limits on the length of the 1044 parameter and of the components that create its internal structure. 1045 Those limits are not altered in any way here. 1046 1047 RFC 1034 imposes no other restrictions upon what kinds of names can 1048 be stored in the DNS. Nor does RFC 1035. This specification, 1049 however, allows only a restricted set of names for the purposes of 1050 the HOST command. Those restrictions can be inferred from the ABNF 1051 grammar given for the "hostname". 1052 10536.3. HOST command semantics 1054 1055 Upon receiving the HOST command, before authenticating the user-PI, a 1056 server-FTP process should validate that the hostname given represents 1057 a valid virtual host for that server, and if so, establish the 1058 appropriate environment for that virtual host. The meaning of that 1059 is not specified here, and may range from doing nothing at all, or 1060 performing a simple change of working directory, to much more 1061 elaborate state changes, as required. 1062 1063 If the hostname specified is unknown at the server, or if the server 1064 is otherwise unwilling to treat the particular connection as a 1065 connection to the hostname specified, the server will respond with a 1066 504 reply. 1067 1068 Note: servers may require that the name specified is in some sense 1069 equivalent to the particular network address that was used to reach 1070 the server. 1071 1072 If the hostname specified would normally be acceptable, but for any 1073 reason is temporarily unavailable, the server SHOULD reply to the 1074 HOST command with a 434 reply. 1075 1076 1077 1078Elz & Hethmon [Expires April 2000] [Page 19] 1079 1080 1081Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 1082 1083 1084 The "220" reply code for the HOST command is the same as the code 1085 used on the initial connection established "welcome" message. This 1086 is done deliberately so as to allow the implementation to implement 1087 the front end FTP server as a wrapper which simply waits for the HOST 1088 command, and then invokes an older, RFC959 compliant, server in the 1089 appropriate environment for the particular hostname received. 1090 10916.3.1. The REIN command 1092 1093 As specified in [3], the REIN command returns the state of the 1094 connection to that it was immediately after the transport connection 1095 was opened. That is not changed here. The effect of a HOST command 1096 will be lost if a REIN command is performed, a new HOST command must 1097 be issued. 1098 1099 Implementors of user-FTP should be aware that server-FTP 1100 implementations which implement the HOST command as a wrapper around 1101 older implementations will be unable to correctly implement the REIN 1102 command. In such an implementation, REIN will typically return the 1103 server-FTP to the state that existed immediately after the HOST 1104 command was issued, instead of to the state immediately after the 1105 connection was opened. 1106 11076.3.2. User-PI usage of HOST 1108 1109 A user-PI that conforms to this specification, MUST send the HOST 1110 command after opening the transport connection, or after any REIN 1111 command, before attempting to authenticate the user with the USER 1112 command. 1113 1114 The following state diagram shows a typical sequence of flow of 1115 control, where the "B" (begin) state is assumed to occur after the 1116 transport connection has opened, or a REIN command has succeeded. 1117 Other commands (such as FEAT [6]) which require no authentication may 1118 have intervened. This diagram is modeled upon (and largely borrowed 1119 from) the similar diagram in section 6 of [3]. 1120 1121 In this diagram, a three digit reply indicates that precise server 1122 reply code, a single digit on a reply path indicates any server reply 1123 beginning with that digit, other than any three digit replies that 1124 might take another path. 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135Elz & Hethmon [Expires April 2000] [Page 20] 1136 1137 1138Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 1139 1140 1141 1142 +---+ HOST +---+ 1,3,5 1143 | B |---------->| W |----------------- 1144 +---+ +---+ | 1145 | | | 1146 2,500,502 | | 4,501,503,504 | 1147 -------------- ------------- | 1148 | | | 1149 V 1 | V 1150 +---+ USER +---+-------------->+---+ 1151 | |---------->| W | 2 ----->| E | 1152 +---+ +---+------ | --->+---+ 1153 | | | | | | 1154 3 | | 4,5 | | | | 1155 -------------- ----- | | | | 1156 | | | | | | 1157 | | | | | | 1158 | --------- | | 1159 | 1| | | | | 1160 V | | | | | 1161 +---+ PASS +---+ 2 | ------->+---+ 1162 | |---------->| W |-------------->| S | 1163 +---+ +---+ ----------->+---+ 1164 | | | | | | 1165 3 | |4,5| | | | 1166 -------------- -------- | | 1167 | | | | | ---- 1168 | | | | | | 1169 | ----------- | 1170 | 1,3| | | | | 1171 V | 2| | | V 1172 +---+ ACCT +---+-- | ------>+---+ 1173 | |---------->| W | 4,5 --------->| F | 1174 +---+ +---+-------------->+---+ 1175 11766.4. HOST command errors 1177 1178 The server-PI shall reply with a 500 or 502 reply if the HOST command 1179 is unrecognized or unimplemented. A 503 reply may be sent if the 1180 HOST command is given after a previous HOST command, or after a user 1181 has been authenticated. Alternately, the server may accept the 1182 command at such a time, with server defined behavior. A 501 reply 1183 should be sent if the hostname given is syntactically invalid, and a 1184 504 reply if a syntactically valid hostname is not a valid virtual 1185 host name for the server. 1186 1187 In all such cases the server-FTP process should act as if no HOST 1188 command had been given. 1189 1190 1191 1192Elz & Hethmon [Expires April 2000] [Page 21] 1193 1194 1195Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 1196 1197 1198 A user-PI receiving a 500 or 502 reply should assume that the 1199 server-PI does not implement the HOST command style virtual server. 1200 It may then proceed to login as if the HOST command had succeeded, 1201 and perhaps, attempt a CWD command to the hostname after 1202 authenticating the user. 1203 1204 A user-PI receiving some other error reply should assume that the 1205 virtual HOST is unavailable, and terminate communications. 1206 1207 A server-PI that receives a USER command, beginning the 1208 authentication sequence, without having received a HOST command 1209 SHOULD NOT reject the USER command. Clients conforming to earlier 1210 FTP specifications do not send HOST commands. In this case the 1211 server may act as if some default virtual host had been explicitly 1212 selected, or may enter an environment different from that of all 1213 supported virtual hosts, perhaps one in which a union of all 1214 available accounts exists, and which presents a NVFS which appears to 1215 contain sub-directories containing the NVFS for all virtual hosts 1216 supported. 1217 12186.5. FEAT response for HOST command 1219 1220 A server-FTP process that supports the host command, and virtual FTP 1221 servers, MUST include in the response to the FEAT command [6], a 1222 feature line indicating that the HOST command is supported. This 1223 line should contain the single word "HOST". This MAY be sent in 1224 upper or lower case, or a mixture of both (it is case insensitive) 1225 but SHOULD be transmitted in upper case only. That is, the response 1226 SHOULD be 1227 1228 C> Feat 1229 S> 211- <any descriptive text> 1230 S> ... 1231 S> HOST 1232 S> ... 1233 S> 211 End 1234 1235 The ellipses indicate place holders where other features may be 1236 included, and are not required. The one space indentation of the 1237 feature lines is mandatory [6]. 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249Elz & Hethmon [Expires April 2000] [Page 22] 1250 1251 1252Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 1253 1254 12557. A Trivial Virtual File Store (TVFS) 1256 1257 Traditionally, FTP has placed almost no constraints upon the file 1258 store (NVFS) provided by a server. This specification does not alter 1259 that. However, it has become common for servers to attempt to 1260 provide at least file system naming conventions modeled loosely upon 1261 those of the UNIX(TM) file system. That is, a tree structured file 1262 system, built of directories, each of which can contain other 1263 directories, or other kinds of files, or both. Each file and 1264 directory has a file name relative to the directory that contains it, 1265 except for the directory at the root of the tree, which is contained 1266 in no other directory, and hence has no name of its own. 1267 1268 That which has so far been described is perfectly consistent with the 1269 standard FTP NVFS and access mechanisms. The "CWD" command is used 1270 to move from one directory to an embedded directory. "CDUP" may be 1271 provided to return to the parent directory, and the various file 1272 manipulation commands ("RETR", "STOR", the rename commands, etc) are 1273 used to manipulate files within the current directory. 1274 1275 However, it is often useful to be able to reference files other than 1276 by changing directories, especially as FTP provides no guaranteed 1277 mechanism to return to a previous directory. The Trivial Virtual 1278 File Store (TVFS), if implemented, provides that mechanism. 1279 12807.1. TVFS File Names 1281 1282 Where a server implements the TVFS, no elementary filename shall 1283 contain the character "/". Where the underlying natural file store 1284 permits files, or directories, to contain the "/" character in their 1285 names, a server-PI implementing TVFS must encode that character in 1286 some manner whenever file or directory names are being returned to 1287 the user-PI, and reverse that encoding whenever such names are being 1288 accepted from the user-PI. 1289 1290 The encoding method to be used is not specified here. Where some 1291 other character is illegal in file and directory names in the 1292 underlying file store, a simple transliteration may be sufficient. 1293 Where there is no suitable substitute character a more complex 1294 encoding scheme, possibly using an escape character, is likely to be 1295 required. 1296 1297 With the one exception of the unnamed root directory, a TVFS file 1298 name may not be empty. That is, all other file names contain at 1299 least one character. 1300 1301 With the sole exception of the "/" character, any valid IS10646 1302 character [11] may be used in a TVFS filename. When transmitted, 1303 1304 1305 1306Elz & Hethmon [Expires April 2000] [Page 23] 1307 1308 1309Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 1310 1311 1312 file name characters are encoded using the UTF-8 encoding [2]. 1313 13147.2. TVFS Path Names 1315 1316 A TVFS "Path Name" combines the file or directory name of a target 1317 file or directory, with the directory names of zero or more enclosing 1318 directories, so as to allow the target file or directory to be 1319 referenced other than when the server's "current working directory" 1320 is the directory directly containing the target file or directory. 1321 1322 By definition, every TVFS file or directory name is also a TVFS path 1323 name. Such a path name is valid to reference the file from the 1324 directory containing the name, that is, when that directory is the 1325 server-FTP's current working directory. 1326 1327 Other TVFS path names are constructed by prefixing a path name by a 1328 name of a directory from which the path is valid, and separating the 1329 two with the "/" character. Such a path name is valid to reference 1330 the file or directory from the directory containing the newly added 1331 directory name. 1332 1333 Where a path name has been extended to the point where the directory 1334 added is the unnamed root directory, the path name will begin with 1335 the "/" character. Such a path is known as a fully qualified path 1336 name. Fully qualified paths may, obviously, not be further extended, 1337 as, by definition, no directory contains the root directory. Being 1338 unnamed, it cannot be represented in any other directory. A fully 1339 qualified path name is valid to reference the named file or directory 1340 from any location (that is, regardless of what the current working 1341 directory may be) in the virtual file store. 1342 1343 Any path name which is not a fully qualified path name may be 1344 referred to as a "relative path name" and will only correctly 1345 reference the intended file when the current working directory of the 1346 server-FTP is a directory from which the relative path name is valid. 1347 1348 As a special case, the path name "/" is defined to be a fully 1349 qualified path name referring to the root directory. That is, the 1350 root directory does not have a directory (or file) name, but does 1351 have a path name. This special path name may be used only as is as a 1352 reference to the root directory. It may not be combined with other 1353 path names using the rules above, as doing so would lead to a path 1354 name containing two consecutive "/" characters, which is an undefined 1355 sequence. 1356 1357 1358 1359 1360 1361 1362 1363Elz & Hethmon [Expires April 2000] [Page 24] 1364 1365 1366Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 1367 1368 13697.2.1. Notes 1370 1371 + It is not required, or expected, that there be only one fully 1372 qualified path name that will reference any particular file or 1373 directory. 1374 + As a caveat, though the TVFS file store is basically tree 1375 structured, there is no requirement that any file or directory 1376 have only one parent directory. 1377 + As defined, no TVFS path name will ever contain two consecutive 1378 "/" characters. Such a name is not illegal however, and may be 1379 defined by the server for any purpose that suits it. Clients 1380 implementing this specification should not assume any semantics 1381 at all for such names. 1382 + Similarly, other than the special case path that refers to the 1383 root directory, no TVFS path name constructed as defined here 1384 will ever end with the "/" character. Such names are also not 1385 illegal, but are undefined. 1386 + While any legal IS10646 character is permitted to occur in a TVFS 1387 file or directory name, other than "/", server FTP 1388 implementations are not required to support all possible IS10646 1389 characters. The subset supported is entirely at the discretion 1390 of the server. The case (where it exists) of the characters that 1391 make up file, directory, and path names may be significant. 1392 Unless determined otherwise by means unspecified here, clients 1393 should assume that all such names are comprised of characters 1394 whose case is significant. Servers are free to treat case (or 1395 any other attribute) of a name as irrelevant, and hence map two 1396 names which appear to be distinct onto the same underlying file. 1397 + There are no defined "magic" names, like ".", ".." or "C:". 1398 Servers may implement such names, with any semantics they choose, 1399 but are not required to do so. 1400 + TVFS imposes no particular semantics or properties upon files, 1401 guarantees no access control schemes, or any of the other common 1402 properties of a file store. Only the naming scheme is defined. 1403 14047.3. FEAT Response for TVFS 1405 1406 In response to the FEAT command [6] a server that wishes to indicate 1407 support for the TVFS as defined here will include a line that begins 1408 with the four characters "TVFS" (in any case, or mixture of cases, 1409 upper case is not required). Servers SHOULD send upper case. 1410 1411 Such a response to the FEAT command MUST NOT be returned unless the 1412 server implements TVFS as defined here. 1413 1414 Later specifications may add to the TVFS definition. Such additions 1415 should be notified by means of additional text appended to the TVFS 1416 feature line. Such specifications, if any, will define the extra 1417 1418 1419 1420Elz & Hethmon [Expires April 2000] [Page 25] 1421 1422 1423Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 1424 1425 1426 text. 1427 1428 Until such a specification is defined, servers should not include 1429 anything after "TVFS" in the TVFS feature line. Clients, however, 1430 should be prepared to deal with arbitrary text following the four 1431 defined characters, and simply ignore it if unrecognized. 1432 1433 A typical response to the FEAT command issued by a server 1434 implementing only this specification would be: 1435 1436 C> feat 1437 S> 211- <any descriptive text> 1438 S> ... 1439 S> TVFS 1440 S> ... 1441 S> 211 end 1442 1443 The ellipses indicate place holders where other features may be 1444 included, and are not required. The one space indentation of the 1445 feature lines is mandatory [6], and is not counted as one of the 1446 first four characters for the purposes of this feature listing. 1447 1448 The TVFS feature adds no new commands to the FTP command repertoire. 1449 14507.4. OPTS for TVFS 1451 1452 There are no options in this TVFS specification, and hence there is 1453 no OPTS command defined. 1454 14557.5. TVFS Examples 1456 1457 Assume a TVFS file store is comprised of a root directory, which 1458 contains two directories (A and B) and two non-directory files (X and 1459 Y). The A directory contains two directories (C and D) and one other 1460 file (Z). The B directory contains just two non-directory files (P 1461 and Q) and the C directory also two non-directory files (also named P 1462 and Q, by chance). The D directory is empty, that is, contains no 1463 files or directories. 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477Elz & Hethmon [Expires April 2000] [Page 26] 1478 1479 1480Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 1481 1482 1483 This structure may depicted graphically as... 1484 1485 (unnamed root) 1486 / | \ \ 1487 / | \ \ 1488 A X B Y 1489 /|\ / \ 1490 / | \ / \ 1491 C D Z P Q 1492 / \ 1493 / \ 1494 P Q 1495 1496 Given this structure, the following fully qualified path names exist. 1497 1498 / 1499 /A 1500 /B 1501 /X 1502 /Y 1503 /A/C 1504 /A/D 1505 /A/Z 1506 /A/C/P 1507 /A/C/Q 1508 /B/P 1509 /B/Q 1510 1511 It is clear that none of the paths / /A /B or /A/D refer to the same 1512 directory, as the contents of each is different. Nor do any of / /A 1513 /A/C or /A/D. However /A/C and /B might be the same directory, there 1514 is insufficient information given to tell. Any of the other path 1515 names (/X /Y /A/Z /A/C/P /A/C/Q /B/P and /B/Q) may refer to the same 1516 underlying files, in almost any combination. 1517 1518 If the current working directory of the server-FTP is /A then the 1519 following path names, in addition to all the fully qualified path 1520 names, are valid 1521 1522 C 1523 D 1524 Z 1525 C/P 1526 C/Q 1527 1528 These all refer to the same files or directories as the corresponding 1529 fully qualified path with "/A/" prepended. 1530 1531 1532 1533 1534Elz & Hethmon [Expires April 2000] [Page 27] 1535 1536 1537Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 1538 1539 1540 That those path names all exist does not imply that the TVFS sever 1541 will necessarily grant any kind of access rights to the named paths, 1542 or that access to the same file via different path names will 1543 necessarily be granted equal rights. 1544 1545 None of the following relative paths are valid when the current 1546 directory is /A 1547 1548 A 1549 B 1550 X 1551 Y 1552 B/P 1553 B/Q 1554 P 1555 Q 1556 1557 Any of those could be made valid by changing the server-FTP's current 1558 working directory to the appropriate directory. Note that the paths 1559 "P" and "Q" might refer to different files depending upon which 1560 directory is selected to cause those to become valid TVFS relative 1561 paths. 1562 15638. Listings for Machine Processing (MLST and MLSD) 1564 1565 The MLST and MLSD commands are intended to standardize the file and 1566 directory information returned by the Server-FTP process. These 1567 commands differ from the LIST command in that the format of the 1568 replies is strictly defined although extensible. 1569 1570 Two commands are defined, MLST which provides data about exactly the 1571 object named on its command line, and no others. MLSD on the other 1572 hand will list the contents of a directory if a directory is named, 1573 otherwise a 501 reply will be returned. In either case, if no object 1574 is named, the current directory is assumed. That will cause MLST to 1575 send a one line response, describing the current directory itself, 1576 and MLSD to list the contents of the current directory. 1577 1578 In the following, the term MLSx will be used wherever either MLST or 1579 MLSD may be inserted. 1580 1581 The MLST and MLSD commands also extend the FTP protocol as presented 1582 in RFC 959 [3] and RFC 1123 [9] to allow that transmission of 8-bit 1583 data over the control connection. Note this is not specifying 1584 character sets which are 8-bit, but specifying that FTP 1585 implementations are to specifically allow the transmission and 1586 reception of 8-bit bytes, with all bits significant, over the control 1587 connection. That is, all 256 possible octet values are permitted. 1588 1589 1590 1591Elz & Hethmon [Expires April 2000] [Page 28] 1592 1593 1594Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 1595 1596 1597 The MLSx command allows both UTF-8/Unicode and "raw" forms as 1598 arguments, and in responses both to the MLST and MLSD commands, and 1599 all other FTP commands which take pathnames as arguments. 1600 16018.1. Format of MLSx Requests 1602 1603 The MLST and MLSD commands each allow a single optional argument. 1604 This argument may be either a directory name or, for MLST only, a 1605 filename. For these purposes, a "filename" is the name of any entity 1606 in the server NVFS which is not a directory. Where TVFS is 1607 supported, any TVFS relative path name valid in the current working 1608 directory, or any TVFS fully qualified path name, may be given. If a 1609 directory name is given then MLSD must return a listing of the 1610 contents of the named directory, otherwise it issues a 501 reply, and 1611 does not open a data connection. In all cases for MLST, a single set 1612 of fact lines (usually a single fact line) containing the information 1613 about the named file or directory shall be returned over the control 1614 connection, without opening a data connection. 1615 1616 If no argument is given then MLSD must return a listing of the 1617 contents of the current working directory, and MLST must return a 1618 listing giving information about the current working directory 1619 itself. For these purposes, the contents of a directory are whatever 1620 filenames (not pathnames) the server-PI will allow to be referenced 1621 when the current working directory is the directory named, and which 1622 the server-PI desires to reveal to the user-PI. 1623 1624 No title, header, or summary, lines, or any other formatting, other 1625 than as is specified below, is ever returned in the output of an MLST 1626 or MLSD command. 1627 1628 If the Client-FTP sends an invalid argument, the Server-FTP MUST 1629 reply with an error code of 501. 1630 1631 The syntax for the MLSx command is: 1632 1633 mlst = "MLst" [ SP pathname ] CRLF 1634 mlsd = "MLsD" [ SP pathname ] CRLF 1635 16368.2. Format of MLSx Response 1637 1638 The format of a response to an MLSx command is as follows: 1639 1640 mlst-response = control-response / error-response 1641 mlsd-response = ( initial-response final-response ) / 1642 error-response 1643 1644 1645 1646 1647 1648Elz & Hethmon [Expires April 2000] [Page 29] 1649 1650 1651Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 1652 1653 1654 control-response = "250-" [ response-message ] CRLF 1655 1*( SP entry CRLF ) 1656 "250" [ SP response-message ] CRLF 1657 1658 initial-response = "150" [ SP response-message ] CRLF 1659 final-response = "226" SP response-message CRLF 1660 1661 response-message = *TCHAR 1662 1663 data-response = *( entry CRLF ) 1664 1665 entry = [ facts ] SP pathname 1666 facts = 1*( fact ";" ) 1667 fact = factname "=" value 1668 factname = "Size" / "Modify" / "Create" / 1669 "Type" / "Unique" / "Perm" / 1670 "Lang" / "Media-Type" / "CharSet" / 1671 os-depend-fact / local-fact 1672 os-depend-fact = <IANA assigned OS name> "." token 1673 local-fact = "X." token 1674 value = *RCHAR 1675 1676 Upon receipt of a MLSx command, the server will verify the parameter, 1677 and if invalid return an error-response. For this purpose, the 1678 parameter should be considered to be invalid if the client issuing 1679 the command does not have permission to perform the request 1680 operation. 1681 1682 If valid, then for an MLST command, the server-PI will send the first 1683 (leading) line of the control response, the entry for the pathname 1684 given, or the current directory if no pathname was provided, and the 1685 terminating line. Normally exactly one entry would be returned, more 1686 entries are permitted only when required to represent a file that is 1687 to have multiple "Type" facts returned. 1688 1689 Note that for MLST the fact set is preceded by a space. That is 1690 provided to guarantee that the fact set cannot be accidentally 1691 interpreted as the terminating line of the control response, but is 1692 required even when that would not be possible. Exactly one space 1693 exists between the set of facts and the pathname. Where no facts are 1694 present, there will be exactly two leading spaces before the 1695 pathname. No spaces are permitted in the facts, any other spaces in 1696 the response are to be treated as being a part of the pathname. 1697 1698 If the command was an MLSD command, the server will open a data 1699 connection as indicated in section 3.2 of RFC959 [3]. If that fails, 1700 the server will return an error-response. If all is OK, the server 1701 will return the initial-response, send the appropriate data-response 1702 1703 1704 1705Elz & Hethmon [Expires April 2000] [Page 30] 1706 1707 1708Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 1709 1710 1711 over the new data connection, close that connection, and then send 1712 the final-response over the control connection. The grammar above 1713 defines the format for the data-response, which defines the format of 1714 the data returned over the data connection established. 1715 1716 The data connection opened for a MLSD response shall be a connection 1717 as if the "TYPE L 8", "MODE S", and "STRU F" commands had been given, 1718 whatever FTP transfer type, mode and structure had actually been set, 1719 and without causing those settings to be altered for future commands. 1720 That is, this transfer type shall be set for the duration of the data 1721 connection established for this command only. While the content of 1722 the data sent can be viewed as a series of lines, implementations 1723 should note that there is no maximum line length defined. 1724 Implementations should be prepared to deal with arbitrarily long 1725 lines. 1726 1727 The facts part of the specification would contain a series of "file 1728 facts" about the file or directory named on the same line. Typical 1729 information to be presented would include file size, last 1730 modification time, creation time, a unique identifier, and a 1731 file/directory flag. 1732 1733 The complete format for a successful reply to the MLSD command would 1734 be: 1735 1736 facts SP pathname CRLF 1737 facts SP pathname CRLF 1738 facts SP pathname CRLF 1739 ... 1740 1741 Note that the format is intended for machine processing, not human 1742 viewing, and as such the format is very rigid. Implementations MUST 1743 NOT vary the format by, for example, inserting extra spaces for 1744 readability, replacing spaces by tabs, including header or title 1745 lines, or inserting blank lines, or in any other way alter this 1746 format. Exactly one space is always required after the set of facts 1747 (which may be empty). More spaces may be present on a line if, and 1748 only if, the file name presented contains significant spaces. The 1749 set of facts must not contain any spaces anywhere inside it. Facts 1750 should be provided in each output line only if they both provide 1751 relevant information about the file named on the same line, and they 1752 are in the set requested by the user-PI. There is no requirement 1753 that the same set of facts be provided for each file, or that the 1754 facts presented occur in the same order for each file. 1755 1756 1757 1758 1759 1760 1761 1762Elz & Hethmon [Expires April 2000] [Page 31] 1763 1764 1765Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 1766 1767 17688.3. Filename encoding 1769 1770 An FTP implementation supporting the MLSx commands must be 8-bit 1771 clean. This is necessary in order to transmit UTF-8 encoded 1772 filenames. This specification recommends the use of UTF-8 encoded 1773 filenames. FTP implementations SHOULD use UTF-8 whenever possible to 1774 encourage the maximum interoperability. 1775 1776 Filenames are not restricted to UTF-8, however treatment of arbitrary 1777 character encodings is not specified by this standard. Applications 1778 are encouraged to treat non-UTF-8 encodings of filenames as octet 1779 sequences. 1780 1781 Note that this encoding is unrelated to that of the contents of the 1782 file, even if the file contains character data. 1783 1784 Further information about filename encoding for FTP may be found in 1785 "Internationalization of the File Transfer Protocol" [7]. 1786 17878.3.1. Notes about the Filename 1788 1789 The filename returned in the MLST response should be the same name as 1790 was specified in the MLST command, or, where TVFS is supported, a 1791 fully qualified TVFS path naming the same file. Where no argument 1792 was given to the MLST command, the server-PI may either include an 1793 empty filename in the response, or it may supply a name that refers 1794 to the current directory, if such a name is available. Where TVFS is 1795 supported, a fully qualified path name of the current directory 1796 SHOULD be returned. 1797 1798 Filenames returned in the output from an MLSD command SHOULD be 1799 unqualified names within the directory named, or the current 1800 directory if no argument was given. That is, the directory named in 1801 the MLSD command SHOULD NOT appear as a component of the filenames 1802 returned. 1803 1804 If the server-FTP process is able, and the "type" fact is being 1805 returned, it MAY return in the MLSD response, an entry whose type is 1806 "cdir", which names the directory from which the contents of the 1807 listing were obtained. Where TVFS is supported, the name MAY be the 1808 fully qualified path name of the directory, or MAY be any other path 1809 name which is valid to refer to that directory from the current 1810 working directory of the server-FTP. Where more than one name 1811 exists, multiple of these entries may be returned. In a sense, the 1812 "cdir" entry can be viewed as a heading for the MLSD output. 1813 However, it is not required to be the first entry returned, and may 1814 occur anywhere within the listing. 1815 1816 1817 1818 1819Elz & Hethmon [Expires April 2000] [Page 32] 1820 1821 1822Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 1823 1824 1825 When TVFS is supported, a user-PI can refer to any file or directory 1826 in the listing by combining a type "cdir" name, with the appropriate 1827 name from the directory listing using the procedure defined in 1828 section 7.2. 1829 1830 Alternatively, whether TVFS is supported or not, the user-PI can 1831 issue a CWD command ([3]) giving a name of type "cdir" from the 1832 listing returned, and from that point reference the files returned in 1833 the MLSD response from which the cdir was obtained by using the 1834 filename components of the listing. 1835 18368.4. Format of Facts 1837 1838 The "facts" for a file in a reply to a MLSx command consist of 1839 information about that file. The facts are a series of keyword=value 1840 pairs each followed by semi-colon (";") characters. An individual 1841 fact may not contain a semi-colon in its name or value. The complete 1842 series of facts may not contain the space character. See the 1843 definition or "RCHAR" in section 2.1 for a list of the characters 1844 that can occur in a fact value. Not all are applicable to all facts. 1845 1846 A sample of a typical series of facts would be: (spread over two 1847 lines for presentation here only) 1848 1849 size=4161;lang=en-US;modify=19970214165800;create=19961001124534; 1850 type=file;x.myfact=foo,bar; 1851 18528.5. Standard Facts 1853 1854 This document defines a standard set of facts as follows: 1855 1856 size -- Size in octets 1857 modify -- Last modification time 1858 create -- Creation time 1859 type -- Entry type 1860 unique -- Unique id of file/directory 1861 perm -- File permissions, whether read, write, execute is 1862 allowed for the login id. 1863 lang -- Language of the filename per IANA[12] registry. 1864 media-type -- MIME media-type of file contents per IANA registry. 1865 charset -- Character set per IANA registry (if not UTF-8) 1866 1867 Fact names are case-insensitive. Size, size, SIZE, and SiZe are the 1868 same fact. 1869 1870 Further operating system specific keywords could be specified by 1871 using the IANA operating system name as a prefix (examples only): 1872 1873 1874 1875 1876Elz & Hethmon [Expires April 2000] [Page 33] 1877 1878 1879Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 1880 1881 1882 OS/2.ea -- OS/2 extended attributes 1883 MACOS.rf -- MacIntosh resource forks 1884 UNIX.mode -- Unix file modes (permissions) 1885 1886 Implementations may define keywords for experimental, or private use. 1887 All such keywords MUST begin with the two character sequence "x.". 1888 As type names are case independent, "x." and "X." are equivalent. 1889 For example: 1890 1891 x.ver -- Version information 1892 x.desc -- File description 1893 x.type -- File type 1894 18958.5.1. The type Fact 1896 1897 The type fact needs a special description. Part of the problem with 1898 current practices is deciding when a file is a directory. If it is a 1899 directory, is it the current directory, a regular directory, or a 1900 parent directory? The MLST specification makes this unambiguous 1901 using the type fact. The type fact given specifies information about 1902 the object listed on the same line of the MLST response. 1903 1904 Five values are possible for the type fact: 1905 1906 file -- a file entry 1907 cdir -- the listed directory 1908 pdir -- a parent directory 1909 dir -- a directory or sub-directory 1910 OS.name=type -- an OS or file system dependent file type 1911 1912 The syntax is defined to be: 1913 1914 type-fact = type-label "=" type-val 1915 type-label = "Type" 1916 type-val = "File" / "cdir" / "pdir" / "dir" / 1917 os-type 1918 19198.5.1.1. type=file 1920 1921 The presence of the type=file fact indicates the listed entry is a 1922 file containing non-system data. That is, it may be transferred from 1923 one system to another of quite different characteristics, and perhaps 1924 still be meaningful. 1925 19268.5.1.2. type=cdir 1927 1928 The type=cdir fact indicates the listed entry contains a pathname of 1929 the directory whose contents are listed. An entry of this type will 1930 1931 1932 1933Elz & Hethmon [Expires April 2000] [Page 34] 1934 1935 1936Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 1937 1938 1939 only be returned as a part of the result of an MLSD command when the 1940 type fact is included, and provides a name for the listed directory, 1941 and facts about that directory. In a sense, it can be viewed as 1942 representing the title of the listing, in a machine friendly format. 1943 It may appear at any point of the listing, it is not restricted to 1944 appearing at the start, though frequently may do so, and may occur 1945 multiple times. It MUST NOT be included if the type fact is not 1946 included, or there would be no way for the user-PI to distinguish the 1947 name of the directory from an entry in the directory. 1948 1949 Where TVFS is supported by the server-FTP, this name may be used to 1950 construct path names with which to refer to the files and directories 1951 returned in the same MLSD output (see section 7.2). These path names 1952 are only expected to work when the server-PI's position in the NVFS 1953 file tree is the same as its position when the MLSD command was 1954 issued, unless a fully qualified path name results. 1955 1956 Where TVFS is not supported, the only defined semantics associated 1957 with a "type=cdir" entry are that, provided the current working 1958 directory of the server-PI has not been changed, a pathname of type 1959 "cdir" may be used as an argument to a CWD command, which will cause 1960 the current directory of the server-PI to change so that the 1961 directory which was listed in its current working directory. 1962 19638.5.1.3. type=dir 1964 1965 If present, the type=dir entry gives the name of a directory. Such 1966 an entry typically cannot be transferred from one system to another 1967 using RETR, etc, but should (permissions permitting) be able to be 1968 the object of an MLSD command. 1969 19708.5.1.4. type=pdir 1971 1972 If present, which will occur only in the response to a MLSD command 1973 when the type fact is included, the type=pdir entry represents a 1974 pathname of the parent directory of the listed directory. As well as 1975 having the properties of a type=dir, a CWD command that uses the 1976 pathname from this entry should change the user to a parent directory 1977 of the listed directory. If the listed directory is the current 1978 directory, a CDUP command may also have the effect of changing to the 1979 named directory. User-FTP processes should note not all responses 1980 will include this information, and that some systems may provide 1981 multiple type=pdir responses. 1982 1983 Where TVFS is supported, a "type=pdir" name may be a relative path 1984 name, or a fully qualified path name. A relative path name will be 1985 relative to the directory being listed, not to the current directory 1986 of the server-PI at the time. 1987 1988 1989 1990Elz & Hethmon [Expires April 2000] [Page 35] 1991 1992 1993Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 1994 1995 1996 For the purposes of this type value, a "parent directory" is any 1997 directory in which there is an entry of type=dir which refers to the 1998 directory in which the type=pdir entity was found. Thus it is not 1999 required that all entities with type=pdir refer to the same 2000 directory. The "unique" fact (if supported) can be used to determine 2001 whether there is a relationship between the type=pdir entries or not. 2002 20038.5.1.5. System defined types 2004 2005 Files types that are specific to a specific operating system, or file 2006 system, can be encoded using the "OS." type names. The format is: 2007 2008 os-type = "OS." os-name "=" os-type 2009 os-name = <an IANA registered operating system name> 2010 os-type = token 2011 2012 The "os-name" indicates the specific system type which supports the 2013 particular localtype. OS specific types are registered by the IANA 2014 using the procedures specified in section 11. The "os-type" provides 2015 the system dependent information as to the type of the file listed. 2016 The os-name and os-type strings in an os-type are case independent. 2017 "OS.unix=block" and "OS.Unix=BLOCK" represent the same type (or 2018 would, if such a type were registered.) 2019 2020 Note: Where the underlying system supports a file type which is 2021 essentially an indirect pointer to another file, the NVFS 2022 representation of that type should normally be to represent the file 2023 which the reference indicates. That is, the underlying basic file 2024 will appear more than once in the NVFS, each time with the "unique" 2025 fact (see immediately following section) containing the same value, 2026 indicating that the same file is represented by all such names. 2027 User-PIs transferring the file need then transfer it only once, and 2028 then insert their own form of indirect reference to construct 2029 alternate names where desired, or perhaps even copy the local file if 2030 that is the only way to provide two names with the same content. A 2031 file which would be a reference to another file, if only the other 2032 file actually existed, may be represented in any OS dependent manner 2033 appropriate, or not represented at all. 2034 20358.5.1.6. Multiple types 2036 2037 Where a file is such that it may validly, and sensibly, treated by 2038 the server-PI as being of more than one of the above types, then 2039 multiple entries should be returned, each with its own "Type" fact of 2040 the appropriate type, and each containing the same pathname. This 2041 may occur, for example, with a structured file, which may contain 2042 sub-files, and where the server-PI permits the structured file to be 2043 treated as a unit, or treated as a directory allowing the sub-files 2044 2045 2046 2047Elz & Hethmon [Expires April 2000] [Page 36] 2048 2049 2050Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 2051 2052 2053 within it to be referenced. 2054 20558.5.2. The unique Fact 2056 2057 The unique fact is used to present a unique identifier for a file or 2058 directory in the NVFS accessed via a server-FTP process. The value 2059 of this fact should be the same for any number of pathnames that 2060 refer to the same underlying file. The fact should have different 2061 values for names which reference distinct files. The mapping between 2062 files, and unique fact tokens should be maintained, and remain 2063 consistent, for at least the lifetime of the control connection from 2064 user-PI to server-PI. 2065 2066 unique-fact = "Unique" "=" token 2067 2068 This fact would be expected to be used by Server-FTPs whose host 2069 system allows things such as symbolic links so that the same file may 2070 be represented in more than one directory on the server. The only 2071 conclusion that should be drawn is that if two different names each 2072 have the same value for the unique fact, they refer to the same 2073 underlying object. The value of the unique fact (the token) should 2074 be considered an opaque string for comparison purposes, and is a case 2075 dependent value. The tokens "A" and "a" do not represent the same 2076 underlying object. 2077 20788.5.3. The modify Fact 2079 2080 The modify fact is used to determine the last time the content of the 2081 file (or directory) indicated was modified. Any change of substance 2082 to the file should cause this value to alter. That is, if a change 2083 is made to a file such that the results of a RETR command would 2084 differ, then the value of the modify fact should alter. User-PIs 2085 should not assume that a different modify fact value indicates that 2086 the file contents are necessarily different than when last retrieved. 2087 Some systems may alter the value of the modify fact for other 2088 reasons, though this is discouraged wherever possible. Also a file 2089 may alter, and then be returned to its previous content, which would 2090 often be indicated as two incremental alterations to the value of the 2091 modify fact. 2092 2093 For directories, this value should alter whenever a change occurs to 2094 the directory such that different filenames would (or might) be 2095 included in MLSD output of that directory. 2096 2097 2098 2099 2100 2101 2102 2103 2104Elz & Hethmon [Expires April 2000] [Page 37] 2105 2106 2107Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 2108 2109 2110 modify-fact = "Modify" "=" time-val 2111 21128.5.4. The create Fact 2113 2114 The create fact indicates when a file, or directory, was first 2115 created. Exactly what "creation" is for this purpose is not 2116 specified here, and may vary from server to server. About all that 2117 can be said about the value returned is that it can never indicate a 2118 later time than the modify fact. 2119 2120 create-fact = "Create" "=" time-val 2121 2122 Implementation Note: Implementors of this fact on UNIX(TM) systems 2123 should note that the unix "stat" "st_ctime" field does not give 2124 creation time, and that unix file systems do not record creation 2125 time at all. Unix (and POSIX) implementations will normally not 2126 include this fact. 2127 21288.5.5. The perm Fact 2129 2130 The perm fact is used to indicate access rights the current FTP user 2131 has over the object listed. Its value is always an unordered 2132 sequence of alphabetic characters. 2133 2134 perm-fact = "Perm" "=" *pvals 2135 pvals = "a" / "c" / "d" / "e" / "f" / 2136 "l" / "m" / "p" / "r" / "w" 2137 2138 There are ten permission indicators currently defined. Many are 2139 meaningful only when used with a particular type of object. The 2140 indicators are case independent, "d" and "D" are the same indicator. 2141 2142 The "a" permission applies to objects of type=file, and indicates 2143 that the APPE (append) command may be applied to the file named. 2144 2145 The "c" permission applies to objects of type=dir (and type=pdir, 2146 type=cdir). It indicates that files may be created in the directory 2147 named. That is, that a STOU command is likely to succeed, and that 2148 STOR and APPE commands might succeed if the file named did not 2149 previously exist, but is to be created in the directory object that 2150 has the "c" permission. It also indicates that the RNTO command is 2151 likely to succeed for names in the directory. 2152 2153 The "d" permission applies to all types. It indicates that the 2154 object named may be deleted, that is, that the RMD command may be 2155 applied to it if it is a directory, and otherwise that the DELE 2156 command may be applied to it. 2157 2158 2159 2160 2161Elz & Hethmon [Expires April 2000] [Page 38] 2162 2163 2164Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 2165 2166 2167 The "e" permission applies to the directory types. When set on an 2168 object of type=dir, type=cdir, or type=pdir it indicates that a CWD 2169 command naming the object should succeed, and the user should be able 2170 to enter the directory named. For type=pdir it also indicates that 2171 the CDUP command may succeed (if this particular pathname is the one 2172 to which a CDUP would apply.) 2173 2174 The "f" permission for objects indicates that the object named may be 2175 renamed - that is, may be the object of an RNFR command. 2176 2177 The "l" permission applies to the directory file types, and indicates 2178 that the listing commands, LIST, NLST, and MLSD may be applied to the 2179 directory in question. 2180 2181 The "m" permission applies to directory types, and indicates that the 2182 MKD command may be used to create a new directory within the 2183 directory under consideration. 2184 2185 The "p" permission applies to directory types, and indicates that 2186 objects in the directory may be deleted, or (stretching naming a 2187 little) that the directory may be purged. Note: it does not indicate 2188 that the RMD command may be used to remove the directory named 2189 itself, the "d" permission indicator indicates that. 2190 2191 The "r" permission applies to type=file objects, and for some 2192 systems, perhaps to other types of objects, and indicates that the 2193 RETR command may be applied to that object. 2194 2195 The "w" permission applies to type=file objects, and for some 2196 systems, perhaps to other types of objects, and indicates that the 2197 STOR command may be applied to the object named. 2198 2199 Note: That a permission indicator is set can never imply that the 2200 appropriate command is guaranteed to work - just that it might. 2201 Other system specific limitations, such as limitations on 2202 available space for storing files, may cause an operation to 2203 fail, where the permission flags may have indicated that it was 2204 likely to succeed. The permissions are a guide only. 2205 2206 Implementation note: The permissions are described here as they apply 2207 to FTP commands. They may not map easily into particular 2208 permissions available on the server's operating system. Servers 2209 are expected to synthesize these permission bits from the 2210 permission information available from operating system. For 2211 example, to correctly determine whether the "D" permission bit 2212 should be set on a directory for a server running on the 2213 UNIX(TM) operating system, the server should check that the 2214 directory named is empty, and that the user has write permission 2215 2216 2217 2218Elz & Hethmon [Expires April 2000] [Page 39] 2219 2220 2221Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 2222 2223 2224 on both the directory under consideration, and its parent 2225 directory. 2226 2227 Some systems may have more specific permissions than those 2228 listed here, such systems should map those to the flags defined 2229 as best they are able. Other systems may have only more broad 2230 access controls. They will generally have just a few possible 2231 permutations of permission flags, however they should attempt to 2232 correctly represent what is permitted. 2233 22348.5.6. The lang Fact 2235 2236 The lang fact describes the natural language of the filename for use 2237 in display purposes. Values used here should be taken from the 2238 language registry of the IANA. See [13] for the syntax, and 2239 procedures, related to language tags. 2240 2241 lang-fact = "Lang" "=" token 2242 2243 Server-FTP implementations MUST NOT guess language values. Language 2244 values must be determined in an unambiguous way such as file system 2245 tagging of language or by user configuration. Note that the lang 2246 fact provides no information at all about the content of a file, only 2247 about the encoding of its name. 2248 22498.5.7. The size Fact 2250 2251 The size fact applies to non-directory file types and should always 2252 reflect the approximate size of the file. This should be as accurate 2253 as the server can make it, without going to extraordinary lengths, 2254 such as reading the entire file. The size is expressed in units of 2255 octets of data in the file. 2256 2257 Given limitations in some systems, Client-FTP implementations must 2258 understand this size may not be precise and may change between the 2259 time of a MLST and RETR operation. 2260 2261 Clients that need highly accurate size information for some 2262 particular reason should use the SIZE command as defined in section 2263 4. The most common need for this accuracy is likely to be in 2264 conjunction with the REST command described in section 5. The size 2265 fact, on the other hand, should be used for purposes such as 2266 indicating to a human user the approximate size of the file to be 2267 transferred, and perhaps to give an idea of expected transfer 2268 completion time. 2269 2270 2271 2272 2273 2274 2275Elz & Hethmon [Expires April 2000] [Page 40] 2276 2277 2278Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 2279 2280 2281 size-fact = "Size" "=" 1*DIGIT 2282 22838.5.8. The media-type Fact 2284 2285 The media-type fact represents the IANA media type of the file named, 2286 and applies only to non-directory types. The list of values used 2287 must follow the guidelines set by the IANA registry. 2288 2289 media-type = "Media-Type" "=" <per IANA guidelines> 2290 2291 Server-FTP implementations MUST NOT guess media type values. Media 2292 type values must be determined in an unambiguous way such as file 2293 system tagging of media-type or by user configuration. This fact 2294 gives information about the content of the file named. Both the 2295 primary media type, and any appropriate subtype should be given, 2296 separated by a slash "/" as is traditional. 2297 22988.5.9. The charset Fact 2299 2300 The charset fact provides the IANA character set name, or alias, for 2301 the encoded pathnames in a MLSx response. The default character set 2302 is UTF-8 unless specified otherwise. FTP implementations SHOULD use 2303 UTF-8 if possible to encourage maximum interoperability. The value 2304 of this fact applies to the pathname only, and provides no 2305 information about the contents of the file. 2306 2307 charset-type = "Charset" "=" token 2308 23098.5.10. Required facts 2310 2311 Servers are not required to support any particular set of the 2312 available facts. However, servers SHOULD, if conceivably possible, 2313 support at least the type, perm, size, unique, and modify facts. 2314 23158.6. System Dependent and Local Facts 2316 2317 By using an system dependent fact, or a local fact, a server-PI may 2318 communicate to the user-PI information about the file named which is 2319 peculiar to the underlying file system. 2320 23218.6.1. System Dependent Facts 2322 2323 System dependent fact names are labeled by prefixing a label 2324 identifying the specific information returned by the name of the 2325 appropriate operating system from the IANA maintained list of 2326 operating system names. 2327 2328 2329 2330 2331 2332Elz & Hethmon [Expires April 2000] [Page 41] 2333 2334 2335Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 2336 2337 2338 The value of an OS dependent fact may be whatever is appropriate to 2339 convey the information available. It must be encoded as a "token" as 2340 defined in section 2.1 however. 2341 2342 In order to allow reliable interoperation between users of system 2343 dependent facts, the IANA will maintain a registry of system 2344 dependent fact names, their syntax, and the interpretation to be 2345 given to their values. Registrations of system dependent facts are 2346 to be accomplished according to the procedures of section 11. 2347 23488.6.2. Local Facts 2349 2350 Implementations may also make available other facts of their own 2351 choosing. As the method of interpretation of such information will 2352 generally not be widely understood, server-PIs should be aware that 2353 clients will typically ignore any local facts provided. As there is 2354 no registration of locally defined facts, it is entirely possible 2355 that different servers will use the same local fact name to provide 2356 vastly different information. Hence user-PIs should be hesitant 2357 about making any use of any information in a locally defined fact 2358 without some other specific assurance that the particular fact is one 2359 that they do comprehend. 2360 2361 Local fact names all begin with the sequence "X.". The rest of the 2362 name is a "token" (see section 2.1). The value of a local fact can 2363 be anything at all, provided it can be encoded as a "token". 2364 23658.7. MLSx Examples 2366 2367 The following examples are all taken from dialogues between existing 2368 FTP clients and servers. Because of this, not all possible 2369 variations of possible response formats are shown in the examples. 2370 This should not be taken as limiting the options of other server 2371 implementors. Where the examples show OS dependent information, that 2372 is to be treated as being purely for the purposes of demonstration of 2373 some possible OS specific information that could be defined. As at 2374 the time of the writing of this document, no OS specific facts or 2375 file types have been defined, the examples shown here should not be 2376 treated as in any way to be preferred over other possible similar 2377 definitions. Consult the IANA registries to determine what types and 2378 facts have been defined. 2379 2380 In the examples shown, only relevant commands and responses have been 2381 included. This is not to imply that other commands (including 2382 authentication, directory modification, PORT or PASV commands, or 2383 similar) would not be present in an actual connection, or were not, 2384 in fact, actually used in the examples before editing. Note also 2385 that the formats shown are those that are transmitted between client 2386 2387 2388 2389Elz & Hethmon [Expires April 2000] [Page 42] 2390 2391 2392Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 2393 2394 2395 and server, not formats which would normally ever be reported to the 2396 user of the client. 2397 2398 In the examples, lines that begin "C> " were sent over the control 2399 connection from the client to the server, lines that begin "S> " were 2400 sent over the control connection from the server to the client, and 2401 lines that begin "D> " were sent from the server to the client over a 2402 data connection created just to send those lines and closed 2403 immediately after. No examples here show data transferred over a 2404 data connection from the client to the server. In all cases, the 2405 prefixes shown above, including the one space, have been added for 2406 the purposes of this document, and are not a part of the data 2407 exchanged between client and server. 2408 24098.7.1. Simple MLST 2410 2411 C> PWD 2412 S> 257 "/tmp" is current directory. 2413 C> MLst cap60.pl198.tar.gz 2414 S> 250- Listing cap60.pl198.tar.gz 2415 S> Type=file;Size=1024990;Perm=r; /tmp/cap60.pl198.tar.gz 2416 S> 250 End 2417 2418 The client first asked to be told the current directory of the 2419 server. This was purely for the purposes of clarity of this example. 2420 The client then requested facts about a specific file. The server 2421 returned the "250-" first control-response line, followed by a single 2422 line of facts about the file, followed by the terminating "250 " 2423 line. The text on the control-response line and the terminating line 2424 can be anything the server decides to send. Notice that the fact 2425 line is indented by a single space. Notice also that there are no 2426 spaces in the set of facts returned, until the single space before 2427 the filename. The filename returned on the fact line is a fully 2428 qualified pathname of the file listed. The facts returned show that 2429 the line refers to a file, that file contains approximately 1024990 2430 bytes, though more or less than that may be transferred if the file 2431 is retrieved, and a different number may be required to store the 2432 file at the client's file store, and the connected user has 2433 permission to retrieve the file but not to do anything else 2434 particularly interesting. 2435 24368.7.2. MLST of a directory 2437 2438 C> PWD 2439 S> 257 "/" is current directory. 2440 C> MLst tmp 2441 S> 250- Listing tmp 2442 S> Type=dir;Modify=19981107085215;Perm=el; /tmp 2443 2444 2445 2446Elz & Hethmon [Expires April 2000] [Page 43] 2447 2448 2449Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 2450 2451 2452 S> 250 End 2453 2454 Again the PWD is just for the purposes of demonstration for the 2455 example. The MLST fact line this time shows that the file listed is 2456 a directory, that it was last modified at 08:52:15 on the 7th of 2457 November, 1998 UTC, and that the user has permission to enter the 2458 directory, and to list its contents, but not to modify it in any way. 2459 Again, the fully qualified path name of the directory listed is 2460 given. 2461 24628.7.3. MLSD of a directory 2463 2464 C> MLSD tmp 2465 S> 150 BINARY connection open for MLSD tmp 2466 D> Type=cdir;Modify=19981107085215;Perm=el; tmp 2467 D> Type=cdir;Modify=19981107085215;Perm=el; /tmp 2468 D> Type=pdir;Modify=19990112030508;Perm=el; .. 2469 D> Type=file;Size=25730;Modify=19940728095854;Perm=; capmux.tar.z 2470 D> Type=file;Size=1830;Modify=19940916055648;Perm=r; hatch.c 2471 D> Type=file;Size=25624;Modify=19951003165342;Perm=r; MacIP-02.txt 2472 D> Type=file;Size=2154;Modify=19950501105033;Perm=r; uar.netbsd.patch 2473 D> Type=file;Size=54757;Modify=19951105101754;Perm=r; iptnnladev.1.0.sit.hqx 2474 D> Type=file;Size=226546;Modify=19970515023901;Perm=r; melbcs.tif 2475 D> Type=file;Size=12927;Modify=19961025135602;Perm=r; tardis.1.6.sit.hqx 2476 D> Type=file;Size=17867;Modify=19961025135602;Perm=r; timelord.1.4.sit.hqx 2477 D> Type=file;Size=224907;Modify=19980615100045;Perm=r; uar.1.2.3.sit.hqx 2478 D> Type=file;Size=1024990;Modify=19980130010322;Perm=r; cap60.pl198.tar.gz 2479 S> 226 MLSD completed 2480 2481 In this example notice that there is no leading space on the fact 2482 lines returned over the data connection. Also notice that two lines 2483 of "type=cdir" have been given. These show two alternate names for 2484 the directory listed, one a fully qualified pathname, and the other a 2485 local name relative to the servers current directory when the MLSD 2486 was performed. Note that all other filenames in the output are 2487 relative to the directory listed, though the server could, if it 2488 chose, give a fully qualified path name for the "type=pdir" line. 2489 This server has chosen not to. The other files listed present a 2490 fairly boring set of files that are present in the listed directory. 2491 Note that there is no particular order in which they are listed. 2492 They are not sorted by filename, by size, or by modify time. Note 2493 also that the "perm" fact has an empty value for the file 2494 "capmux.tar.z" indicating that the connected user has no permissions 2495 at all for that file. This server has chosen to present the "cdir" 2496 and "pdir" lines before the lines showing the content of the 2497 directory, it is not required to do so. The "size" fact does not 2498 provide any meaningful information for a directory, so is not 2499 included in the fact lines for the directory types shown. 2500 2501 2502 2503Elz & Hethmon [Expires April 2000] [Page 44] 2504 2505 2506Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 2507 2508 25098.7.4. A more complex example 2510 2511 C> MLst test 2512 S> 250- Listing test 2513 S> Type=dir;Perm=el;Unique=keVO1+ZF4 test 2514 S> 250 End 2515 C> MLSD test 2516 S> 150 BINARY connection open for MLSD test 2517 D> Type=cdir;Perm=el;Unique=keVO1+ZF4; test 2518 D> Type=pdir;Perm=e;Unique=keVO1+d?3; .. 2519 D> Type=OS.unix=slink:/foobar;Perm=;Unique=keVO1+4G4; foobar 2520 D> Type=OS.unix=chr-13/29;Perm=;Unique=keVO1+5G4; device 2521 D> Type=OS.unix=blk-11/108;Perm=;Unique=keVO1+6G4; block 2522 D> Type=file;Perm=awr;Unique=keVO1+8G4; writable 2523 D> Type=dir;Perm=cpmel;Unique=keVO1+7G4; promiscuous 2524 D> Type=dir;Perm=;Unique=keVO1+1t2; no-exec 2525 D> Type=file;Perm=r;Unique=keVO1+EG4; two words 2526 D> Type=file;Perm=r;Unique=keVO1+IH4; leading space 2527 D> Type=file;Perm=r;Unique=keVO1+1G4; file1 2528 D> Type=dir;Perm=cpmel;Unique=keVO1+7G4; incoming 2529 D> Type=file;Perm=r;Unique=keVO1+1G4; file2 2530 D> Type=file;Perm=r;Unique=keVO1+1G4; file3 2531 D> Type=file;Perm=r;Unique=keVO1+1G4; file4 2532 S> 226 MLSD completed 2533 C> MLSD test/incoming 2534 S> 150 BINARY connection open for MLSD test/incoming 2535 D> Type=cdir;Perm=cpmel;Unique=keVO1+7G4; test/incoming 2536 D> Type=pdir;Perm=el;Unique=keVO1+ZF4; .. 2537 D> Type=file;Perm=awdrf;Unique=keVO1+EH4; bar 2538 D> Type=file;Perm=awdrf;Unique=keVO1+LH4; 2539 D> Type=file;Perm=rf;Unique=keVO1+1G4; file5 2540 D> Type=file;Perm=rf;Unique=keVO1+1G4; file6 2541 D> Type=dir;Perm=cpmdelf;Unique=keVO1+!s2; empty 2542 S> 226 MLSD completed 2543 2544 For the purposes of this example the fact set requested has been 2545 modified to delete the "size" and "modify" facts, and add the 2546 "unique" fact. First, facts about a filename have been obtained via 2547 MLST. Note that no fully qualified path name was given this time. 2548 That was because the server was unable to determine that information. 2549 Then having determined that the filename represents a directory, that 2550 directory has been listed. That listing also shows no fully 2551 qualified path name, for the same reason, thus has but a single 2552 "type=cdir" line. This directory (which was created especially for 2553 the purpose) contains several interesting files. There are some with 2554 OS dependent file types, several sub-directories, and several 2555 ordinary files. 2556 2557 2558 2559 2560Elz & Hethmon [Expires April 2000] [Page 45] 2561 2562 2563Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 2564 2565 2566 Not much can be said here about the OS dependent file types, as none 2567 of the information shown there should be treated as any more than 2568 possibilities. It can be seen that the OS type of the server is 2569 "unix" though, which is one of the OS types in the IANA registry of 2570 Operating System names. 2571 2572 Of the three directories listed, "no-exec" has no permission granted 2573 to this user to access at all. From the "Unique" fact values, it can 2574 be determined that "promiscuous" and "incoming" in fact represent the 2575 same directory. Its permissions show that the connected user has 2576 permission to do essentially anything other than to delete the 2577 directory. That directory was later listed. It happens that the 2578 directory can not be deleted because it is not empty. 2579 2580 Of the normal files listed, two contain spaces in their names. The 2581 file called " leading space" actually contains two spaces in its 2582 name, one before the "l" and one between the "g" and the "s". The 2583 two spaces that separate the facts from the visible part of the path 2584 name make that clear. The file "writable" has the "a" and "w" 2585 permission bits set, and consequently the connected user should be 2586 able to STOR or APPE to that file. 2587 2588 The other four file names, "file1", "file2", "file3", and "file4" all 2589 represent the same underlying file, as can be seen from the values of 2590 the "unique" facts of each. It happens that "file1" and "file2" are 2591 Unix "hard" links, and that "file3" and "file4" are "soft" or 2592 "symbolic" links to the first two. None of that information is 2593 available via standard MLST facts, it is sufficient for the purposes 2594 of FTP to note that all represent the same file, and that the same 2595 data would be fetched no matter which of them was retrieved, and that 2596 all would be simultaneously modified were data stored in any. 2597 2598 Finally, the sub-directory "incoming" is listed. Since "promiscuous" 2599 is the same directory there would be no point listing it as well. In 2600 that directory, the files "file5" and "file6" represent still more 2601 names for the "file1" file we have seen before. Notice the entry 2602 between that for "bar" and "file5". Though it is not possible to 2603 easily represent it in this document, that shows a file with a name 2604 comprising exactly three spaces (" "). A client will have no 2605 difficulty determining that name from the output presented to it 2606 however. The directory "empty" is, as its name implies, empty, 2607 though that is not shown here. It can, however, be deleted, as can 2608 file "bar" and the file whose name is three spaces. All the files 2609 that reside in this directory can be renamed. This is a consequence 2610 of the UNIX semantics of the directory that contains them being 2611 modifiable. 2612 2613 2614 2615 2616 2617Elz & Hethmon [Expires April 2000] [Page 46] 2618 2619 2620Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 2621 2622 26238.7.5. More accurate time information 2624 2625 C> MLst file1 2626 S> 250- Listing file1 2627 S> Type=file;Modify=19990929003355.237; file1 2628 S> 250 End 2629 2630 In this example, the server-FTP is indicating that "file1" was last 2631 modified 237 milliseconds after 00:33:55 UTC on the 29th of 2632 September, 1999. 2633 26348.7.6. A different server 2635 2636 C> MLST 2637 S> 250-Begin 2638 S> type=dir;unique=AQkAAAAAAAABCAAA; / 2639 S> 250 End. 2640 C> MLSD . 2641 S> 150 Opening ASCII mode data connection for MLS. 2642 D> type=cdir;unique=AQkAAAAAAAABCAAA; / 2643 D> type=dir;unique=AQkAAAAAAAABEAAA; bin 2644 D> type=dir;unique=AQkAAAAAAAABGAAA; etc 2645 D> type=dir;unique=AQkAAAAAAAAB8AwA; halflife 2646 D> type=dir;unique=AQkAAAAAAAABoAAA; incoming 2647 D> type=dir;unique=AQkAAAAAAAABIAAA; lib 2648 D> type=dir;unique=AQkAAAAAAAABWAEA; linux 2649 D> type=dir;unique=AQkAAAAAAAABKAEA; ncftpd 2650 D> type=dir;unique=AQkAAAAAAAABGAEA; outbox 2651 D> type=dir;unique=AQkAAAAAAAABuAAA; quake2 2652 D> type=dir;unique=AQkAAAAAAAABQAEA; winstuff 2653 S> 226 Listing completed. 2654 C> MLSD linux 2655 S> 150 Opening ASCII mode data connection for MLS. 2656 D> type=cdir;unique=AQkAAAAAAAABWAEA; /linux 2657 D> type=pdir;unique=AQkAAAAAAAABCAAA; / 2658 D> type=dir;unique=AQkAAAAAAAABeAEA; firewall 2659 D> type=file;size=12;unique=AQkAAAAAAAACWAEA; helo_world 2660 D> type=dir;unique=AQkAAAAAAAABYAEA; kernel 2661 D> type=dir;unique=AQkAAAAAAAABmAEA; scripts 2662 D> type=dir;unique=AQkAAAAAAAABkAEA; security 2663 S> 226 Listing completed. 2664 C> MLSD linux/kernel 2665 S> 150 Opening ASCII mode data connection for MLS. 2666 D> type=cdir;unique=AQkAAAAAAAABYAEA; /linux/kernel 2667 D> type=pdir;unique=AQkAAAAAAAABWAEA; /linux 2668 D> type=file;size=6704;unique=AQkAAAAAAAADYAEA; k.config 2669 D> type=file;size=7269221;unique=AQkAAAAAAAACYAEA; linux-2.0.36.tar.gz 2670 D> type=file;size=12514594;unique=AQkAAAAAAAAEYAEA; linux-2.1.130.tar.gz 2671 2672 2673 2674Elz & Hethmon [Expires April 2000] [Page 47] 2675 2676 2677Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 2678 2679 2680 S> 226 Listing completed. 2681 2682 Note that this server returns its "unique" fact value in quite a 2683 different format. It also returns fully qualified path names for the 2684 "pdir" entry. 2685 26868.7.7. Some IANA files 2687 2688 C> MLSD . 2689 S> 150 BINARY connection open for MLSD . 2690 D> Type=cdir;Modify=19990219183438; /iana/assignments 2691 D> Type=pdir;Modify=19990112030453; .. 2692 D> Type=dir;Modify=19990219073522; media-types 2693 D> Type=dir;Modify=19990112033515; character-set-info 2694 D> Type=dir;Modify=19990112033529; languages 2695 D> Type=file;Size=44242;Modify=19990217230400; character-sets 2696 D> Type=file;Size=1947;Modify=19990209215600; operating-system-names 2697 S> 226 MLSD completed 2698 C> MLSD media-types 2699 S> 150 BINARY connection open for MLSD media-types 2700 D> Type=cdir;Modify=19990219073522; media-types 2701 D> Type=cdir;Modify=19990219073522; /iana/assignments/media-types 2702 D> Type=pdir;Modify=19990219183438; .. 2703 D> Type=dir;Modify=19990112033045; text 2704 D> Type=dir;Modify=19990219183442; image 2705 D> Type=dir;Modify=19990112033216; multipart 2706 D> Type=dir;Modify=19990112033254; video 2707 D> Type=file;Size=30249;Modify=19990218032700; media-types 2708 S> 226 MLSD completed 2709 C> MLSD character-set-info 2710 S> 150 BINARY connection open for MLSD character-set-info 2711 D> Type=cdir;Modify=19990112033515; character-set-info 2712 D> Type=cdir;Modify=19990112033515; /iana/assignments/character-set-info 2713 D> Type=pdir;Modify=19990219183438; .. 2714 D> Type=file;Size=1234;Modify=19980903020400; windows-1251 2715 D> Type=file;Size=4557;Modify=19980922001400; tis-620 2716 D> Type=file;Size=801;Modify=19970324130000; ibm775 2717 D> Type=file;Size=552;Modify=19970320130000; ibm866 2718 D> Type=file;Size=922;Modify=19960505140000; windows-1258 2719 S> 226 MLSD completed 2720 C> MLSD languages 2721 S> 150 BINARY connection open for MLSD languages 2722 D> Type=cdir;Modify=19990112033529; languages 2723 D> Type=cdir;Modify=19990112033529; /iana/assignments/languages 2724 D> Type=pdir;Modify=19990219183438; .. 2725 D> Type=file;Size=2391;Modify=19980309130000; default 2726 D> Type=file;Size=943;Modify=19980309130000; tags 2727 D> Type=file;Size=870;Modify=19971026130000; navajo 2728 2729 2730 2731Elz & Hethmon [Expires April 2000] [Page 48] 2732 2733 2734Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 2735 2736 2737 D> Type=file;Size=699;Modify=19950911140000; no-bok 2738 S> 226 MLSD completed 2739 C> PWD 2740 S> 257 "/iana/assignments" is current directory. 2741 2742 This example shows some of the IANA maintained files that are 2743 relevant for this specification in MLSD format. Note that these 2744 listings have been edited by deleting many entries, the actual 2745 listings are much longer. 2746 27478.7.8. A stress test of case (in)dependence 2748 2749 The following example is intended to make clear some cases where case 2750 dependent strings are permitted in the MLSx commands, and where case 2751 independent strings are required. 2752 2753 C> MlsD . 2754 S> 150 BINARY connection open for MLSD . 2755 D> Type=pdir;Modify=19990929011228;Perm=el;Unique=keVO1+ZF4; .. 2756 D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+Bd8; FILE2 2757 D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+aG8; file3 2758 D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+ag8; FILE3 2759 D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+bD8; file1 2760 D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+bD8; file2 2761 D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+Ag8; File3 2762 D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+bD8; File1 2763 D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+Bd8; File2 2764 D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+bd8; FILE1 2765 S> 226 MLSD completed 2766 2767 Note first that the "MLSD" command, shown here as "MlsD" is case 2768 independent. Clients may issue this command in any case, or 2769 combination of cases, they desire. This is the case for all FTP 2770 commands. 2771 2772 Next, notice the labels of the facts. These are also case 2773 independent strings, Server-FTP is permitted to return them in any 2774 case they desire. User-FTP must be prepared to deal with any case, 2775 though it may do this by mapping the labels to a common case if 2776 desired. 2777 2778 Then, notice that there are nine objects of "type" file returned. In 2779 a case independent NVFS these would represent three different file 2780 names, "file1", "file2", and "file3". With a case dependent NVFS all 2781 nine represent different file names. Either is possible, server-FTPs 2782 may implement a case dependent or a case independent NVFS. User-FTPs 2783 must allow for case dependent selection of files to manipulate on the 2784 server. 2785 2786 2787 2788Elz & Hethmon [Expires April 2000] [Page 49] 2789 2790 2791Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 2792 2793 2794 Lastly, notice that the value of the "unique" fact is case dependent. 2795 In the example shown, "file1", "File1", and "file2" all have the same 2796 "unique" fact value "keVO1+bD8", and thus all represent the same 2797 underlying file. On the other hand, "FILE1" has a different "unique" 2798 fact value ("keVO1+bd8") and hence represents a different file. 2799 Similarly, "FILE2" and "File2" are two names for the same underlying 2800 file, whereas "file3", "File3" and "FILE3" all represent different 2801 underlying files. 2802 2803 That the approximate sizes ("size" fact) and last modification times 2804 ("modify" fact) are the same in all cases might be no more than a 2805 coincidence. 2806 2807 It is not suggested that the operators of server-FTPs create NVFS 2808 which stress the protocols to this extent, however both user and 2809 server implementations must be prepared to deal with such extreme 2810 examples. 2811 28128.8. FEAT response for MLSx 2813 2814 When responding to the FEAT command, a server-FTP process that 2815 supports MLST, and MLSD, plus internationalization of pathnames, MUST 2816 indicate that this support exists. It does this by including a MLST 2817 feature line. As well as indicating the basic support, the MLST 2818 feature line indicates which MLST facts are available from the 2819 server, and which of those will be returned if no subsequent "OPTS 2820 MLST" command is sent. 2821 2822 mlst-feat = SP "MLST" [SP factlist] CRLF 2823 factlist = 1*( factname ["*"] ";" ) 2824 2825 The initial space shown in the mlst-feat response is that required by 2826 the FEAT command, two spaces are not permitted. If no factlist is 2827 given, then the server-FTP process is indicating that it supports 2828 MLST, but implements no facts. Only pathnames can be returned. This 2829 would be a minimal MLST implementation, and useless for most 2830 practical purposes. Where the factlist is present, the factnames 2831 included indicate the facts supported by the server. Where the 2832 optional asterisk appears after a factname, that fact will be 2833 included in MLST format responses, until an "OPTS MLST" is given to 2834 alter the list of facts returned. After that, subsequent FEAT 2835 commands will return the asterisk to show the facts selected by the 2836 most recent "OPTS MLST". 2837 2838 Note that there is no distinct FEAT output for MLSD. The presence of 2839 the MLST feature indicates that both MLST and MLSD are supported. 2840 2841 2842 2843 2844 2845Elz & Hethmon [Expires April 2000] [Page 50] 2846 2847 2848Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 2849 2850 28518.8.1. Examples 2852 2853 C> Feat 2854 S> 211- Features supported 2855 S> REST STREAM 2856 S> MDTM 2857 S> SIZE 2858 S> TVFS 2859 S> UTF8 2860 S> MLST Type*;Size*;Modify*;Perm*;Unique*;UNIX.mode;UNIX.chgd;X.hidden; 2861 S> 211 End 2862 2863 Aside from some features irrelevant here, this server indicates that 2864 it supports MLST including several, but not all, standard facts, all 2865 of which it will send by default. It also supports two OS dependent 2866 facts, and one locally defined fact. The latter three must be 2867 requested expressly by the client for this server to supply them. 2868 2869 C> Feat 2870 S> 211-Extensions supported: 2871 S> CLNT 2872 S> MDTM 2873 S> MLST type*;size*;modify*;UNIX.mode*;UNIX.owner;UNIX.group;unique; 2874 S> PASV 2875 S> REST STREAM 2876 S> SIZE 2877 S> TVFS 2878 S> Compliance Level: 19981201 (IETF mlst-05) 2879 S> 211 End. 2880 2881 Again, in addition to some irrelevant features here, this server 2882 indicates that it supports MLST, four of the standard facts, one of 2883 which ("unique") is not enabled by default, and several OS dependent 2884 facts, one of which is provided by the server by default. This 2885 server actually supported more OS dependent facts. Others were 2886 deleted for the purposes of this document to comply with document 2887 formatting restrictions. 2888 28898.9. OPTS parameters for MLST 2890 2891 For the MLSx commands, the Client-FTP may specify a list of facts it 2892 wishes to be returned in all subsequent MLSx commands until another 2893 OPTS MLST command is sent. The format is specified by: 2894 2895 2896 2897 2898 2899 2900 2901 2902Elz & Hethmon [Expires April 2000] [Page 51] 2903 2904 2905Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 2906 2907 2908 mlst-opts = "OPTS" SP "MLST" 2909 [ SP 1*( factname ";" ) ] 2910 2911 By sending the "OPTS MLST" command, the client requests the server to 2912 include only the facts listed as arguments to the command in 2913 subsequent output from MLSx commands. Facts not included in the 2914 "OPTS MLST" command MUST NOT be returned by the server. Facts that 2915 are included should be returned for each entry returned from the MLSx 2916 command where they meaningfully apply. Facts requested that are not 2917 supported, or which are inappropriate to the file or directory being 2918 listed should simply be omitted from the MLSx output. This is not an 2919 error. Note that where no factname arguments are present, the client 2920 is requesting that only the file names be returned. In this case, 2921 and in any other case where no facts are included in the result, the 2922 space that separates the fact names and their values from the file 2923 name is still required. That is, the first character of the output 2924 line will be a space, (or two characters will be spaces when the line 2925 is returned over the control connection,) and the file name will 2926 start immediately thereafter. 2927 2928 Clients should note that generating values for some facts can be 2929 possible, but very expensive, for some servers. It is generally 2930 acceptable to retrieve any of the facts that the server offers as its 2931 default set before any "OPTS MLST" command has been given, however 2932 clients should use particular caution before requesting any facts not 2933 in that set. That is, while other facts may be available from the 2934 server, clients should refrain from requesting such facts unless 2935 there is a particular operational requirement for that particular 2936 information, which ought be more significant than perhaps simply 2937 improving the information displayed to an end user. 2938 2939 Note, there is no "OPTS MLSD" command, the fact names set with the 2940 "OPTS MLST" command apply to both MLST and MLSD commands. 2941 2942 Servers are not required to accept "OPTS MLST" commands before 2943 authentication of the user-PI, but may choose to permit them. 2944 29458.9.1. OPTS MLST Response 2946 2947 The "response-message" from [6] to a successful OPTS MLST command has 2948 the following syntax. 2949 2950 mlst-opt-resp = "MLST OPTS" [ SP 1*( factname ";" ) ] 2951 2952 This defines the "response-message" as used in the "opts-good" 2953 message in RFC2389 [6]. 2954 2955 2956 2957 2958 2959Elz & Hethmon [Expires April 2000] [Page 52] 2960 2961 2962Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 2963 2964 2965 The facts named in the response are those which the server will now 2966 include in MLST (and MLSD) response, after the processing of the 2967 "OPTS MLST" command. Any facts from the request not supported by the 2968 server will be omitted from this response message. If no facts will 2969 be included, the list of facts will be empty. Note that the list of 2970 facts returned will be the same as those marked by a trailing 2971 asterisk ("*") in a subsequent FEAT command response. There is no 2972 requirement that the order of the facts returned be the same as that 2973 in which they were requested, or that in which they will be listed in 2974 a FEAT command response, or that in which facts are returned in MLST 2975 responses. The fixed string "MLST OPTS" in the response may be 2976 returned in any case, or mixture of cases. 2977 29788.9.2. Examples 2979 2980 C> Feat 2981 S> 211- Features supported 2982 S> MLST Type*;Size;Modify*;Perm;Unique;UNIX.mode;UNIX.chgd;X.hidden; 2983 S> 211 End 2984 C> OptS Mlst Type;UNIX.mode;Perm; 2985 S> 201 MLST OPTS Type;Perm;UNIX.mode; 2986 C> Feat 2987 S> 211- Features supported 2988 S> MLST Type*;Size;Modify;Perm*;Unique;UNIX.mode*;UNIX.chgd;X.hidden; 2989 S> 211 End 2990 C> opts MLst lang;type;charset;create; 2991 S> 201 MLST OPTS Type; 2992 C> Feat 2993 S> 211- Features supported 2994 S> MLST Type*;Size;Modify;Perm;Unique;UNIX.mode;UNIX.chgd;X.hidden; 2995 S> 211 End 2996 C> OPTS mlst size;frogs; 2997 S> 201 MLST OPTS Size; 2998 C> Feat 2999 S> 211- Features supported 3000 S> MLST Type;Size*;Modify;Perm;Unique;UNIX.mode;UNIX.chgd;X.hidden; 3001 S> 211 End 3002 C> opts MLst unique type; 3003 S> 501 Invalid MLST options 3004 C> Feat 3005 S> 211- Features supported 3006 S> MLST Type;Size*;Modify;Perm;Unique;UNIX.mode;UNIX.chgd;X.hidden; 3007 S> 211 End 3008 3009 For the purposes of this example, features other than MLST have been 3010 deleted from the output to avoid clutter. The example shows the 3011 initial default feature output for MLST. The facts requested are 3012 then changed by the client. The first change shows facts that are 3013 3014 3015 3016Elz & Hethmon [Expires April 2000] [Page 53] 3017 3018 3019Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 3020 3021 3022 available from the server being selected. Subsequent FEAT output 3023 shows the altered features as being returned. The client then 3024 attempts to select some standard features which the server does not 3025 support. This is not an error, however the server simply ignores the 3026 requests for unsupported features, as the FEAT output that follows 3027 shows. Then, the client attempts to request a non-standard, and 3028 unsupported, feature. The server ignores that, and selects only the 3029 supported features requested. Lastly, the client sends a request 3030 containing a syntax error (spaces cannot appear in the factlist.) The 3031 server-FTP sends an error response and completely ignores the 3032 request, leaving the fact set selected as it had been previously. 3033 3034 Note that in all cases, except the error response, the response lists 3035 the facts that have been selected. 3036 3037 C> Feat 3038 S> 211- Features supported 3039 S> MLST Type*;Size*;Modify*;Perm*;Unique*;UNIX.mode;UNIX.chgd;X.hidden; 3040 S> 211 End 3041 C> Opts MLST 3042 S> 201 MLST OPTS 3043 C> Feat 3044 S> 211- Features supported 3045 S> MLST Type;Size;Modify;Perm;Unique;UNIX.mode;UNIX.chgd;X.hidden; 3046 S> 211 End 3047 C> MLst tmp 3048 S> 250- Listing tmp 3049 S> /tmp 3050 S> 250 End 3051 C> OPTS mlst unique;size; 3052 S> 201 MLST OPTS Size;Unique; 3053 C> MLst tmp 3054 S> 250- Listing tmp 3055 S> Unique=keVO1+YZ5; /tmp 3056 S> 250 End 3057 C> OPTS mlst unique;type;modify; 3058 S> 201 MLST OPTS Type;Modify;Unique; 3059 C> MLst tmp 3060 S> 250- Listing tmp 3061 S> Type=dir;Modify=19990930152225;Unique=keVO1+YZ5; /tmp 3062 S> 250 End 3063 C> OPTS mlst fish;cakes; 3064 S> 201 MLST OPTS 3065 C> MLst tmp 3066 S> 250- Listing tmp 3067 S> /tmp 3068 S> 250 End 3069 C> OptS Mlst Modify;Unique; 3070 3071 3072 3073Elz & Hethmon [Expires April 2000] [Page 54] 3074 3075 3076Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 3077 3078 3079 S> 201 MLST OPTS Modify;Unique; 3080 C> MLst tmp 3081 S> 250- Listing tmp 3082 S> Modify=19990930152225;Unique=keVO1+YZ5; /tmp 3083 S> 250 End 3084 C> opts MLst fish cakes; 3085 S> 501 Invalid MLST options 3086 C> MLst tmp 3087 S> 250- Listing tmp 3088 S> Modify=19990930152225;Unique=keVO1+YZ5; /tmp 3089 S> 250 End 3090 3091 This example shows the effect of changing the facts requested upon 3092 subsequent MLST commands. Notice that a syntax error leaves the set 3093 of selected facts unchanged. Also notice exactly two spaces 3094 preceding the pathname when no facts were selected, either 3095 deliberately, or because none of the facts requested were available. 3096 30979. Impact On Other FTP Commands 3098 3099 Along with the introduction of MLST, traditional FTP commands must be 3100 extended to allow for the use of more than US-ASCII or EBCDIC 3101 character sets. In general, the support of MLST requires support for 3102 arbitrary character sets wherever filenames and directory names are 3103 allowed. This applies equally to both arguments given to the 3104 following commands and to the replies from them, as appropriate. 3105 3106 CWD 3107 RETR 3108 STOR 3109 STOU 3110 APPE 3111 RNFR 3112 RNTO 3113 DELE 3114 RMD 3115 MKD 3116 PWD 3117 STAT 3118 3119 The arguments to all of these commands should be processed the same 3120 way that MLST commands and responses are processed with respect to 3121 handling embedded spaces, CRs and NULs. See section 2.2. 3122 3123 3124 3125 3126 3127 3128 3129 3130Elz & Hethmon [Expires April 2000] [Page 55] 3131 3132 3133Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 3134 3135 313610. Character sets and Internationalization 3137 3138 FTP commands are protocol elements, and are always expressed in 3139 ASCII. FTP responses are composed of the numeric code, which is a 3140 protocol element, and a message, which is often expected to convey 3141 information to the user. It is not expected that users normally 3142 interact directly with the protocol elements, rather the user FTP- 3143 process constructs the commands, and interprets the results, in the 3144 manner best suited for the particular user. Explanatory text in 3145 responses generally has no particular meaning to the protocol. The 3146 numeric codes provide all necessary information. Server-PIs are free 3147 to provide the text in any language that can be adequately 3148 represented in ASCII, or where an alternative language and 3149 representation has been negotiated (see [7]) in that language and 3150 representation. 3151 3152 Pathnames are expected to be encoded in UTF-8 allowing essentially 3153 any character to be represented in a pathname. Meaningful pathnames 3154 are defined by the server NVFS. 3155 3156 No restrictions at all are placed upon the contents of files 3157 transferred using the FTP protocols. Unless the "media-type" fact is 3158 provided in a MLSx response nor is any advice given here which would 3159 allow determining the content type. That information is assumed to 3160 be obtained via other means. 3161 316211. IANA Considerations 3163 3164 This specification makes use of some lists of values currently 3165 maintained by the IANA, and creates two new lists for the IANA to 3166 maintain. It does not add any values to any existing registries. 3167 3168 The existing IANA registries used by this specification are modified 3169 using mechanisms specified elsewhere. 3170 317111.1. The OS specific fact registry 3172 3173 A registry of OS specific fact names shall be maintained by the IANA. 3174 The OS names for the OS portion of the fact name must be taken from 3175 the IANA's list of registered OS names. To add a fact name to this 3176 OS specific registry of OS specific facts, an applicant must send to 3177 the IANA a request, in which is specified the OS name, the OS 3178 specific fact name, a definition of the syntax of the fact value, 3179 which must conform to the syntax of a token as given in this 3180 document, and a specification of the semantics to be associated with 3181 the particular fact and its values. Upon receipt of such an 3182 application, and if the combination of OS name and OS specific fact 3183 name has not been previously defined, the IANA will add the 3184 3185 3186 3187Elz & Hethmon [Expires April 2000] [Page 56] 3188 3189 3190Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 3191 3192 3193 specification to the registry. 3194 3195 Any examples of OS specific facts found in this document are to be 3196 treated as examples of possible OS specific facts, and do not form a 3197 part of the IANA's registry merely because of being included in this 3198 document. 3199 320011.2. The OS specific filetype registry 3201 3202 A registry of OS specific file types shall be maintained by the IANA. 3203 The OS names for the OS portion of the fact name must be taken from 3204 the IANA's list of registered OS names. To add a file type to this 3205 OS specific registry of OS specific file types, an applicant must 3206 send to the IANA a request, in which is specified the OS name, the OS 3207 specific file type, a definition of the syntax of the fact value, 3208 which must conform to the syntax of a token as given in this 3209 document, and a specification of the semantics to be associated with 3210 the particular fact and its values. Upon receipt of such an 3211 application, and if the combination of OS name and OS specific file 3212 type has not been previously defined, the IANA will add the 3213 specification to the registry. 3214 3215 Any examples of OS specific file types found in this document are to 3216 be treated as potential OS specific file types only, and do not form 3217 a part of the IANA's registry merely because of being included in 3218 this document. 3219 322012. Security Considerations 3221 3222 This memo does not directly concern security. It is not believed 3223 that any of the mechanisms documented here impact in any particular 3224 way upon the security of FTP. 3225 3226 Implementing the SIZE command, and perhaps some of the facts of the 3227 MDLx commands, may impose a considerable load on the server, which 3228 could lead to denial of service attacks. Servers have, however, 3229 implemented this for many years, without significant reported 3230 difficulties. 3231 3232 With the introduction of virtual hosts to FTP, and the possible 3233 accompanying multiple authentication environments, server 3234 implementors will need to take some care to ensure that integrity is 3235 maintained. 3236 3237 The FEAT and OPTS commands may be issued before the FTP 3238 authentication has occurred [6]. This allows unauthenticated clients 3239 to determine which of the features defined here are supported, and to 3240 negotiate the fact list for MLSx output. No actual MLSx commands may 3241 3242 3243 3244Elz & Hethmon [Expires April 2000] [Page 57] 3245 3246 3247Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 3248 3249 3250 be issued however, and no problems with permitting the selection of 3251 the format prior to authentication are foreseen. 3252 3253 A general discussion of issues related to the security of FTP can be 3254 found in [14]. 3255 325613. References 3257 3258 [1] Coded Character Set--7-bit American Standard Code for Information 3259 Interchange, ANSI X3.4-1986. 3260 3261 [2] Yergeau, F., "UTF-8, a transformation format of Unicode and ISO 3262 10646", RFC 2044, October 1996. 3263 3264 [3] Postel, J., Reynolds, J., "File Transfer Protocol (FTP)", 3265 STD 9, RFC 959, October 1985 3266 3267 [4] Bradner, S., "Key words for use in RFCs to Indicate 3268 Requirement Levels", BCP 14, RFC 2119, March 1997 3269 3270 [5] Crocker, D., Overell, P., "Augmented BNF for Syntax 3271 Specifications: ABNF", RFC 2234, November 1997 3272 3273 [6] Hethmon, P., Elz, R., "Feature negotiation mechanism for the 3274 File Transfer Protocol", RFC 2389, August 1998 3275 3276 [7] Curtin, W., "Internationalization of the File Transfer Protocol", 3277 RFC 2640, July 1999 3278 3279 [8] Postel, J., Reynolds, J., "Telnet protocol Specification" 3280 STD 8, RFC 854, May 1983 3281 3282 [9] Braden, R,. "Requirements for Internet Hosts -- Application 3283 and Support", STD 3, RFC 1123, October 1989 3284 3285 [10] Mockapetris, P., "Domain Names - Concepts and Facilities" 3286 STD 13, RFC 1034, November 1987 3287 3288 [11] ISO/IEC 10646-1:1993 "Universal multiple-octet coded character set 3289 (UCS) -- Part 1: Architecture and basic multilingual plane", 3290 International Standard -- Information Technology, 1993 3291 3292 [12] Internet Assigned Numbers Authority. http://www.iana.org 3293 Email: iana@iana.org. 3294 3295 [13] Alvestrand, H., "Tags for the Identification of Languages" 3296 RFC 1766, March 1995 3297 3298 3299 3300 3301Elz & Hethmon [Expires April 2000] [Page 58] 3302 3303 3304Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 3305 3306 3307 [14] Allman, M., Ostermann, S., "FTP Security Considerations" 3308 RFC 2577, May 1999 3309 3310Acknowledgments 3311 3312 This document is a product of the FTPEXT working group of the IETF. 3313 3314 The following people are among those who have contributed to this 3315 document: 3316 3317 Alex Belits 3318 D. J. Bernstein 3319 Dave Cridland 3320 Martin J. Duerst 3321 Mike Gleason 3322 Mark Harris 3323 Alun Jones 3324 James Matthews 3325 Luke Mewburn 3326 Jan Mikkelsen 3327 Keith Moore 3328 Buz Owen 3329 Mark Symons 3330 Stephen Tihor 3331 and the entire FTPEXT working group of the IETF. 3332 3333 Apologies are offered to any inadvertently omitted. 3334 3335 Bernhard Rosenkraenzer suggested the HOST command, and initially 3336 described it. 3337 3338 The description of the modifications to the REST command and the MDTM 3339 and SIZE commands comes from a set of modifications suggested for 3340 RFC959 by Rick Adams in 1989. A draft containing just those 3341 commands, edited by David Borman, has been merged with this document. 3342 3343 Mike Gleason provided access to the FTP server used in some of the 3344 examples. 3345 3346 All of the examples in this document are taken from actual 3347 client/server exchanges, though some have been edited for brevity, or 3348 to meet document formatting requirements. 3349 3350 3351 3352 3353 3354 3355 3356 3357 3358Elz & Hethmon [Expires April 2000] [Page 59] 3359 3360 3361Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 3362 3363 3364Copyright 3365 3366 This document is in the public domain. Any and all copyright 3367 protection that might apply in any jurisdiction is expressly 3368 disclaimed. 3369 3370Editors' Addresses 3371 3372 Robert Elz 3373 University of Melbourne 3374 Department of Computer Science 3375 Parkville, Vic 3052 3376 Australia 3377 3378 Email: kre@munnari.OZ.AU 3379 3380 3381 Paul Hethmon 3382 Hethmon Brothers 3383 2305 Chukar Road 3384 Knoxville, TN 37923 USA 3385 3386 Phone: +1 423 690 8990 3387 Email: phethmon@hethmon.com 3388 3389 3390 3391 3392 3393 3394 3395 3396 3397 3398 3399 3400 3401 3402 3403 3404 3405 3406 3407 3408 3409 3410 3411 3412 3413 3414 3415Elz & Hethmon [Expires April 2000] [Page 60] 3416