Add heimdal-0.6.3
[dragonfly.git] / crypto / heimdal-0.6.3 / doc / standardisation / draft-ietf-ftpext-mlst-08.txt
1 FTPEXT Working Group                                              R. Elz
2 Internet Draft                                   University of Melbourne
3 Expiration 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
15 Status 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
52 Elz & Hethmon             [Expires April 2000]                  [Page 1]
53
54
55 Internet Draft       draft-ietf-ftpext-mlst-08.txt          October 1999
56
57
58 Abstract
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
109 Elz & Hethmon             [Expires April 2000]                  [Page 2]
110
111
112 Internet Draft       draft-ietf-ftpext-mlst-08.txt          October 1999
113
114
115
116
117 Table 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
166 Elz & Hethmon             [Expires April 2000]                  [Page 3]
167
168
169 Internet 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
187 1. 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
205 2. 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
223 Elz & Hethmon             [Expires April 2000]                  [Page 4]
224
225
226 Internet 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
233 2.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
267 2.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
280 Elz & Hethmon             [Expires April 2000]                  [Page 5]
281
282
283 Internet 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
320 2.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
337 Elz & Hethmon             [Expires April 2000]                  [Page 6]
338
339
340 Internet Draft       draft-ietf-ftpext-mlst-08.txt          October 1999
341
342
343 2.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
357 2.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
394 Elz & Hethmon             [Expires April 2000]                  [Page 7]
395
396
397 Internet 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
407 2.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
428 3. 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
451 Elz & Hethmon             [Expires April 2000]                  [Page 8]
452
453
454 Internet 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
467 3.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
488 3.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
497 3.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
508 Elz & Hethmon             [Expires April 2000]                  [Page 9]
509
510
511 Internet 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
525 3.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
565 Elz & Hethmon             [Expires April 2000]                 [Page 10]
566
567
568 Internet 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
574 4. 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
595 4.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
611 4.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
622 Elz & Hethmon             [Expires April 2000]                 [Page 11]
623
624
625 Internet Draft       draft-ietf-ftpext-mlst-08.txt          October 1999
626
627
628 4.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
647 4.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
679 Elz & Hethmon             [Expires April 2000]                 [Page 12]
680
681
682 Internet Draft       draft-ietf-ftpext-mlst-08.txt          October 1999
683
684
685 5. 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
704 5.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
736 Elz & Hethmon             [Expires April 2000]                 [Page 13]
737
738
739 Internet 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
750 5.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
766 5.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
793 Elz & Hethmon             [Expires April 2000]                 [Page 14]
794
795
796 Internet 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
850 Elz & Hethmon             [Expires April 2000]                 [Page 15]
851
852
853 Internet Draft       draft-ietf-ftpext-mlst-08.txt          October 1999
854
855
856 5.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
877 5.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
895 6. 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
907 Elz & Hethmon             [Expires April 2000]                 [Page 16]
908
909
910 Internet 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
964 Elz & Hethmon             [Expires April 2000]                 [Page 17]
965
966
967 Internet Draft       draft-ietf-ftpext-mlst-08.txt          October 1999
968
969
970 6.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
993 6.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
1021 Elz & Hethmon             [Expires April 2000]                 [Page 18]
1022
1023
1024 Internet 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
1053 6.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
1078 Elz & Hethmon             [Expires April 2000]                 [Page 19]
1079
1080
1081 Internet 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
1091 6.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
1107 6.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
1135 Elz & Hethmon             [Expires April 2000]                 [Page 20]
1136
1137
1138 Internet 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
1176 6.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
1192 Elz & Hethmon             [Expires April 2000]                 [Page 21]
1193
1194
1195 Internet 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
1218 6.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
1249 Elz & Hethmon             [Expires April 2000]                 [Page 22]
1250
1251
1252 Internet Draft       draft-ietf-ftpext-mlst-08.txt          October 1999
1253
1254
1255 7. 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
1280 7.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
1306 Elz & Hethmon             [Expires April 2000]                 [Page 23]
1307
1308
1309 Internet Draft       draft-ietf-ftpext-mlst-08.txt          October 1999
1310
1311
1312    file name characters are encoded using the UTF-8 encoding [2].
1313
1314 7.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
1363 Elz & Hethmon             [Expires April 2000]                 [Page 24]
1364
1365
1366 Internet Draft       draft-ietf-ftpext-mlst-08.txt          October 1999
1367
1368
1369 7.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
1404 7.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
1420 Elz & Hethmon             [Expires April 2000]                 [Page 25]
1421
1422
1423 Internet 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
1450 7.4. OPTS for TVFS
1451
1452    There are no options in this TVFS specification, and hence there is
1453    no OPTS command defined.
1454
1455 7.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
1477 Elz & Hethmon             [Expires April 2000]                 [Page 26]
1478
1479
1480 Internet 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
1534 Elz & Hethmon             [Expires April 2000]                 [Page 27]
1535
1536
1537 Internet 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
1563 8. 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
1591 Elz & Hethmon             [Expires April 2000]                 [Page 28]
1592
1593
1594 Internet 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
1601 8.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
1636 8.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
1648 Elz & Hethmon             [Expires April 2000]                 [Page 29]
1649
1650
1651 Internet 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
1705 Elz & Hethmon             [Expires April 2000]                 [Page 30]
1706
1707
1708 Internet 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
1762 Elz & Hethmon             [Expires April 2000]                 [Page 31]
1763
1764
1765 Internet Draft       draft-ietf-ftpext-mlst-08.txt          October 1999
1766
1767
1768 8.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
1787 8.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
1819 Elz & Hethmon             [Expires April 2000]                 [Page 32]
1820
1821
1822 Internet 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
1836 8.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
1852 8.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
1876 Elz & Hethmon             [Expires April 2000]                 [Page 33]
1877
1878
1879 Internet 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
1895 8.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
1919 8.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
1926 8.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
1933 Elz & Hethmon             [Expires April 2000]                 [Page 34]
1934
1935
1936 Internet 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
1963 8.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
1970 8.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
1990 Elz & Hethmon             [Expires April 2000]                 [Page 35]
1991
1992
1993 Internet 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
2003 8.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
2035 8.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
2047 Elz & Hethmon             [Expires April 2000]                 [Page 36]
2048
2049
2050 Internet Draft       draft-ietf-ftpext-mlst-08.txt          October 1999
2051
2052
2053    within it to be referenced.
2054
2055 8.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
2078 8.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
2104 Elz & Hethmon             [Expires April 2000]                 [Page 37]
2105
2106
2107 Internet Draft       draft-ietf-ftpext-mlst-08.txt          October 1999
2108
2109
2110         modify-fact  = "Modify" "=" time-val
2111
2112 8.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
2128 8.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
2161 Elz & Hethmon             [Expires April 2000]                 [Page 38]
2162
2163
2164 Internet 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
2218 Elz & Hethmon             [Expires April 2000]                 [Page 39]
2219
2220
2221 Internet 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
2234 8.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
2249 8.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
2275 Elz & Hethmon             [Expires April 2000]                 [Page 40]
2276
2277
2278 Internet Draft       draft-ietf-ftpext-mlst-08.txt          October 1999
2279
2280
2281         size-fact  = "Size" "=" 1*DIGIT
2282
2283 8.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
2298 8.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
2309 8.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
2315 8.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
2321 8.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
2332 Elz & Hethmon             [Expires April 2000]                 [Page 41]
2333
2334
2335 Internet 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
2348 8.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
2365 8.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
2389 Elz & Hethmon             [Expires April 2000]                 [Page 42]
2390
2391
2392 Internet 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
2409 8.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
2436 8.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
2446 Elz & Hethmon             [Expires April 2000]                 [Page 43]
2447
2448
2449 Internet 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
2462 8.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
2503 Elz & Hethmon             [Expires April 2000]                 [Page 44]
2504
2505
2506 Internet Draft       draft-ietf-ftpext-mlst-08.txt          October 1999
2507
2508
2509 8.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
2560 Elz & Hethmon             [Expires April 2000]                 [Page 45]
2561
2562
2563 Internet 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
2617 Elz & Hethmon             [Expires April 2000]                 [Page 46]
2618
2619
2620 Internet Draft       draft-ietf-ftpext-mlst-08.txt          October 1999
2621
2622
2623 8.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
2634 8.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
2674 Elz & Hethmon             [Expires April 2000]                 [Page 47]
2675
2676
2677 Internet 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
2686 8.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
2731 Elz & Hethmon             [Expires April 2000]                 [Page 48]
2732
2733
2734 Internet 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
2747 8.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
2788 Elz & Hethmon             [Expires April 2000]                 [Page 49]
2789
2790
2791 Internet 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
2812 8.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
2845 Elz & Hethmon             [Expires April 2000]                 [Page 50]
2846
2847
2848 Internet Draft       draft-ietf-ftpext-mlst-08.txt          October 1999
2849
2850
2851 8.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
2889 8.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
2902 Elz & Hethmon             [Expires April 2000]                 [Page 51]
2903
2904
2905 Internet 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
2945 8.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
2959 Elz & Hethmon             [Expires April 2000]                 [Page 52]
2960
2961
2962 Internet 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
2978 8.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
3016 Elz & Hethmon             [Expires April 2000]                 [Page 53]
3017
3018
3019 Internet 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
3073 Elz & Hethmon             [Expires April 2000]                 [Page 54]
3074
3075
3076 Internet 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
3097 9. 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
3130 Elz & Hethmon             [Expires April 2000]                 [Page 55]
3131
3132
3133 Internet Draft       draft-ietf-ftpext-mlst-08.txt          October 1999
3134
3135
3136 10. 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
3162 11. 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
3171 11.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
3187 Elz & Hethmon             [Expires April 2000]                 [Page 56]
3188
3189
3190 Internet 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
3200 11.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
3220 12. 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
3244 Elz & Hethmon             [Expires April 2000]                 [Page 57]
3245
3246
3247 Internet 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
3256 13. 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
3301 Elz & Hethmon             [Expires April 2000]                 [Page 58]
3302
3303
3304 Internet 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
3310 Acknowledgments
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
3358 Elz & Hethmon             [Expires April 2000]                 [Page 59]
3359
3360
3361 Internet Draft       draft-ietf-ftpext-mlst-08.txt          October 1999
3362
3363
3364 Copyright
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
3370 Editors' 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
3415 Elz & Hethmon             [Expires April 2000]                 [Page 60]