[Docs] [txt|pdf] [Tracker] [WG] [Email] [Nits]

Versions: 00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 RFC 3659

FTPEXT Working Group                                          P. Hethmon
Internet Draft                                          Hethmon Brothers
Expiration Date: September 1997
                                                                  R. Elz
                                                 University of Melbourne

                                                              March 1997


                   MLST Command and Extensions to FTP


                     draft-ietf-ftpext-mlst-00.txt

Status of this Memo

   This document is an Internet-Draft.  Internet-Drafts are working
   documents of the Internet Engineering Task Force (IETF), its areas,
   and its working groups.  Note that other groups may also distribute
   working documents as Internet-Drafts.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   To learn the current status of any Internet-Draft, please check the
   "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow
   Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe),
   munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or
   ftp.isi.edu (US West Coast).

Abstract

   In order to overcome the problems inherent in the current FTP LIST
   output, a new command is needed to transfer standardized listing
   information from Server-FTP to Client-FTP.  In addition, a way for
   the Server-FTP to let the Client-FTP know of this capability without
   imposing on the Client-FTP to randomly try new commands is needed.
   This proposal meets both of these requirements.

   This proposal also extends the FTP protocol to allow character sets
   other than US-ASCII[1] by allowing the transmission of 8-bit
   characters and the recommended use of UTF-8[2] encoding.

   This version of the document corrects some aspects of the previous
   draft, which was filed as: draft-hethmon-mlst-command-ftp-01.txt in
   particular some of the details of the ABNF used.  It also adds some



Hethmon & Elz                                                   [Page 1]


Internet Draft       draft-ietf-ftpext-mlst-00.txt            March 1997


   editorial notes where questions to be resolved still exist.  This
   paragraph will be deleted from the final version of this document.


Table of Contents

         Status of this Memo  ......................................   1
         Abstract  .................................................   1
    1    Introduction  .............................................   3
    2    Knowledge of Extra Capabilities  ..........................   3
    2.1  The FEAT Command  .........................................   3
    2.2  Rationale for FEAT  .......................................   4
    3    MLST and MLSD Specification  ..............................   4
    3.1  Generalities  .............................................   4
    3.2  Encoding the data  ........................................   5
    3.3  Format of MLST Request  ...................................   5
    3.4  Format of MLST Response  ..................................   6
    3.5  Filename encoding  ........................................   7
    3.6  Format of Facts  ..........................................   7
    3.7  Standard Facts  ...........................................   8
    3.8  The type Fact  ............................................   9
    3.9  The unique Fact  ..........................................  11
    3.10 The perm Fact  ............................................  12
    3.11 The lang Fact  ............................................  15
    3.12 The size Fact  ............................................  15
    3.13 The media-type Fact  ......................................  15
    3.14 The charset Fact  .........................................  16
    3.15 Mandatory minimum reply for MLST  .........................  16
    4    The OPTS Command  .........................................  16
    4.1  OPTS parameters for MLST  .................................  16
    4.2  Using OPTS to select MLST output connection  ..............  17
    5    Impact On Other FTP Commands  .............................  17
    5.1  Impact on Pathnames and Filenames  ........................  18
    6    Security  .................................................  18
    7    References  ...............................................  18
         Acknowledgements  .........................................  19
         Editors' Addresses  .......................................  19














Hethmon & Elz                                                   [Page 2]


Internet Draft       draft-ietf-ftpext-mlst-00.txt            March 1997


1. Introduction

   This document amends the File Transfer Protocol (FTP) [6].  Four new
   commands are added, "FEAT", "OPTS", "MLST", and "MLSD".  These
   commands allow a client to discover which optional commands a server
   supports, and how they are supported, to select among various options
   that any FTP command may support, and most importantly, to obtain a
   directory listing in a machine friendly, predictable, way.

2. Knowledge of Extra Capabilities

2.1. The FEAT Command

   In order for the Client-FTP to know whether the Server-FTP
   understands the MLST command and future extensions to the FTP
   protocol, a new command, FEAT, can be used for the Client-FTP to
   query the Server-FTP on any extensions from RFC959 [6] the Server-FTP
   supports.  For Server-FTP's which do not support any extensions, the
   FEAT command may result in a 500 reply.

   The request syntax in augmented BNF syntax [3]: Note that literal
   strings in ABNF are case independent, where case dependence is
   required, terminal are, and must be, expressed as numeric strings.

        feat = feat-cmd CRLF
        feat-cmd = "feat"

   For Server-FTP's which do support extensions the correct reply code
   will be 211.  The reply to the FEAT command will typically be a
   multiline reply of the form:

        C> FEAT
        S> 211- Extensions supported:
        S>  MLST size*,create,modify*,perm,media-type
        S>  SIZE
        S>  MDTM
        S> 211 End

   Each extension supported must be listed on a separate line to
   facilitate the possible inclusion of parameters supported by each
   extension command.  Any parameters included are to be specified in
   the RFC defining that extension.

        feat-response = "211-" SP *CHAR CRLF *( SP feature CRLF )
                        "211" SP "End" CRLF
        feature       = 1*CHAR [ SP parms ]
        parms         = 1*CHAR




Hethmon & Elz                                                   [Page 3]


Internet Draft       draft-ietf-ftpext-mlst-00.txt            March 1997


   FTP implementations which support MLST or other extension commands
   MUST support FEAT.

2.2. Rationale for FEAT

   While not absolutely necessary, a standard mechanism for the Server-
   FTP to inform the Client-FTP of any features and extensions supported
   will help reduce unnecessary traffic between the Client-FTP and
   Server-FTP as more extensions may be introduced in the future.  If no
   mechanism exists for this, a Client-FTP will have to try each
   extension in turn for the Server-FTP resulting in a series of
   exchanges.

   It is also suggested for Client-FTP which retain information about a
   particular Server-FTP between uses that they cache the knowledge of a
   particular Server-FTP supporting extensions.  A Client-FTP would be
   expected to re-query the Server-FTP if any cached extension resulted
   in a 500 response code, or if the Client-FTP needs to determine the
   support for a newly introduced extension.

   [ Ed-Note: It has been questioned whether this paragraph is needed,
               or whether it may encourage behavior that we might with
               hindsight have preferred not to encourage.  Opinions? ]

3. MLST and MLSD Specification

3.1. Generalities

   The MLST command is intended to standardize the file and directory
   information returned by the Server-FTP process.  The MLST command
   differs from the LIST and NLST commands in that responses can be sent
   over either the control connection or data connection.  The default
   is to send responses over the data connection. It also differs in
   that the format of the replies is strictly defined although
   extensible.

   Two commands are defined, MLST which provides data about exactly the
   object named on its command line, and no others.  MLSD on the other
   hand will list the contents of a directory if a directory is named,
   otherwise it is identical to MLST.  If no object is named, the
   current directory is assumed.  That will cause MLST to send a one
   line response, and MLSD to list the contents of the current
   directory.

   In the sequel only MLST will be described, other than as previously
   mentioned, MLSD is identical.





Hethmon & Elz                                                   [Page 4]


Internet Draft       draft-ietf-ftpext-mlst-00.txt            March 1997


   The MLST and MLSD commands also extend the FTP protocol as presented
   in RFC 959 [6] and RFC 1123 to allow that transmission of 8-bit data.
   Note this is not specifying character sets which are 8-bit, but
   specifying that FTP implementations are to specifically allow 8-bit
   bytes.  The MLST command allows both UTF-8/Unicode and "raw" forms as
   arguments.

   The MLST response is allowed over either the data connection or over
   the control connection.  The default is to send the response over the
   data connection.  Client-FTPs which wish to receive the response over
   the control connection must use the OPTS command as described in
   Section 4 to set the default response to use the control connection.

3.2. Encoding the data

   MLST commands and responses may contain arbitrary binary data, yet
   the data must be divided into lines for correct interpretation.  Each
   line is terminated with the two character ascii sequence carriage
   return, and line feed, in that order, with no intervening data.

   To allow that sequence to be transmitted as part of the data, without
   confusion, a NUL (character with binary value of 0) must be
   transmitted after every carriage-return character that is not the
   first half of the CRLF line terminating pair.  This is to be done
   regardless of what character follows the CR.

   Upon reception, exactly one NUL character (if present) must be
   deleted after any received CR, and that CR must then not be treated
   as being a part of a line terminator, regardless of what character
   follows the deleted NUL.

   Implementations should take care to correctly process all possible
   octet values, including the zero value (NUL character), as part of
   the MLST command or response.

3.3. Format of MLST Request

   The MLST command allows a single optional argument.  This argument
   may be either a directory name or a filename.  If a directory name is
   given then MLST must return a listing of the contents of the named
   directory.  If the argument is a filename, then MLST must return only
   a single fact line containing the information about the named file.

   If no argument is given then MLST must return a listing of the
   contents of the current working directory.

   If the Client-FTP sends an invalid argument, the Server-FTP MUST
   reply with an error code of 501.



Hethmon & Elz                                                   [Page 5]


Internet Draft       draft-ietf-ftpext-mlst-00.txt            March 1997


   The syntax for the MLST command is:

        mlst       = mlst-cmd [ SP ( utf-8-name / raw ) ] CRLF
        mlst-cmd   = "mlst"
        utf-8-name = <a UTF-8 encoded Unicode string>
        raw        = <any other 8-bit octet string>

3.4. Format of MLST Response

   The format of a response to the MLST command is as follows:

        mlst-response         = mlst-control-response /
                                mlst-data-response
        mlst-control-response = "212-" CRLF *(SP entry CRLF)
                                "212" SP end-token CRLF
        entry                 = *facts SP ( utf-8-name / raw )
        facts                 = fact *( ";" fact )
        fact                  = name "=" value
        end-token             = %h45.6e.64      ; "End" exactly as shown
        name                  = 1*ltext
        value                 = 1*ltext
        ltext                 = ALPHA / DIGIT / "," / "." / ":" / "!" /
                                "@" / "#" / "$" / "%" / "^" /
                                "&" / "(" / ")" / "-" / "_" /
                                "+" / "?" / "/" / "\" / "'" /
                                %h22     ; <"> -- double quote character
        mlst-data-response    = initial-response CRLF final-response
        initial-response      = "150" SP response-message CRLF
        response-message      = *ltext
        final-response        = "226" SP response-message CRLF

   When responses are sent over the data connection, the format of the
   control connection response is that of mlst-data-response.  When the
   response is sent over the control connection, then the mlst-control-
   response format is used.

   Given the path lengths available on various operating systems, this
   specification requires implementations to accept a minimum line
   length (for the entire line of a MLST reply, including the
   terminating CRLF, but not including null characters added after
   embedded CRs) of at least 2048 bytes.  It would be recommended that
   lengths of up to 4096 bytes be accepted if limits are necessary.

   The facts part of the specification would contain a series of "file
   facts" about the file/directory.  Typical information to be presented
   would include file size, last modification time, creation time,
   unique identifier, file/directory flag.




Hethmon & Elz                                                   [Page 6]


Internet Draft       draft-ietf-ftpext-mlst-00.txt            March 1997


   The complete format for a successful reply to the MLST command would
   be (over the control connection):

        C> MLST
        S> 212-
        S>  facts utf-8-name
        S>  facts utf-8-name
        S>  facts utf-8-name
        S> 212 End

3.5. Filename encoding

   A FTP implementation using the MLST command must be 8-bit clean.
   This is necessary in order to transmit UTF-8 encoded filenames.  This
   specification recommends the use of UTF-8 encoded filenames.  FTP
   implementations SHOULD use UTF-8 whenever possible to encourage the
   maximum interoperability.

   Filenames are not restricted to UTF-8, however treatment of arbitrary
   character encodings is not specified by this standard.  Applications
   are encouraged to treat non-UTF-8 encodings of filenames as octet
   sequences.

   Note that this encoding DOES NOT apply to the contents of the file.

   Further information about filename encoding for FTP may be found in
   "Internationalization of the File Transfer Protocol" [4].

3.5.1. Notes about the Filename

   The filename returned in the MLST command should be an unqualified
   filename.  No path information should be given.  Path information is
   to be returned separately as specified in Section 3.7.

   [ Ed-Note: This reference to section 3.7 came from the previous
               version of the draft.  I am not sure it makes sense, but
               nor am I sure what it should be changed to, if 3.7 is not
               correct. ]

3.6. Format of Facts

   The "facts" for a file in a reply to a MLST command consist of
   information about that file.  The facts are a series of keyword=value
   pairs separated by a semi-colon (";") character.  The complete series
   of facts may not contain the space character.

   A sample of a typical series of facts would be: (spread over two
   lines for presentation only)



Hethmon & Elz                                                   [Page 7]


Internet Draft       draft-ietf-ftpext-mlst-00.txt            March 1997


        size=4161;lang=en-us;modify=19970214165800;create=19961001124534;
        type=file;x.myfact=foo,bar

3.7. Standard Facts

   This document defines a standard set of facts as follows:

        size       -- Size in bytes
        modify     -- Last modification time
        create     -- Creation time
        type       -- Entry type
        unique     -- Unique id of file/directory
        perm       -- File permissions, whether read, write, execute is
                      allowed for the login id.
        lang       -- Language of the filename per IANA[5] registry.
        media-type -- MIME media-type of file contents per IANA registry.
        charset    -- Character set per IANA registry (if not UTF-8)

   Fact names are case-sensitive.  Size, size, and SIze are not the
   same.

   For keywords specifying time, the time is to be specified in one of
   the formats:

        yyyymmddhhmmss.sss

   or

        yyyymmddhhmmss

   where

        yyyy -- 4 digit year
        mm   -- 2 digit month
        dd   -- 2 digit day
        hh   -- 2 digit hour
        ss   -- 2 digit second
        .sss -- optional digits for thousandths of a second

   [ Ed-Note: in the REST/MDTM/SIZE draft, the "sss" is permitted to be
               however long (accurate) the sender desires, is there ay
               reason here to make an incompatible spec? ]

   In ABNF, the syntax of a time value is:







Hethmon & Elz                                                   [Page 8]


Internet Draft       draft-ietf-ftpext-mlst-00.txt            March 1997


        time-val = 12*12DIGIT [ "." 1*DIGIT ]

   Time values are always represented in UTC (GMT).

   Further operating system specific keywords could be specified by
   using the IANA operating system name as a prefix (examples only):

        OS/2.ea  -- OS/2 extended attributes
        MACOS.rf -- MacIntosh resource forks

   Implementation specific keywords would be allowed by starting the
   keyword with the sequence "x.":

        x.ver  -- Version information
        x.desc -- File description
        x.type -- File type

   [ Ed-Note: is the "x" in lower case only? ]

3.8. The type Fact

   The type fact needs a special description.  Part of the problem with
   current practices is deciding when a file is a directory.  If it is a
   directory, is it the current directory, a regular directory, or a
   parent directory?  The MLST specification makes this unambiguous
   using the type fact.  The type fact given specifies information about
   the object listed on the same line of the MLST response.

   Five values are possible for the type fact:

        file -- a file entry
        cdir -- the current directory
        pdir -- the parent directory
        dir  -- a directory or sub-directory
        link -- the entry is a link to a file or directory

   The syntax is defined to be:

        type-fact  = type-label "=" type-val
        type-label = %h64.79.70.65                ; "type" in lower case
        type-val   = %h66.69.6c.65                              ; "file"
                     / %h63.64.69.72                            ; "cdir"
                     / %h70.64.69.72                            ; "pdir"
                     / %h64.69.72                               ; "dir"
                     / %h6c.69.6e.6b                            ; "link"






Hethmon & Elz                                                   [Page 9]


Internet Draft       draft-ietf-ftpext-mlst-00.txt            March 1997


   [ Ed-Note: do we need to permit OS dependent file types? ]

3.8.1. type=file

   The presence of the type=file fact indicates the listed entry is a
   file containing non-system data.  That is, it may be transferred from
   one system to another, and perhaps be meaningful.

3.8.2. type=cdir

   The type=cdir fact indicates the listed entry is the full, qualified
   pathname of the directory whose contents are listed.  The value of
   this entry (the filename part) plus the value of a type=file entry
   together should represent a complete pathname suitable for a RETR
   command.  The value for the type=cdir entry should include any
   necessary system delimiters used between path components.  An example
   would be the forward slash "/" on a Unix system, or a back slash "\"
   on an OS/2 or Windows system.

   The type=cdir entry is required for all MLST replies which return
   directory listings.  It is not required for MLST replies which return
   information about a single file.

   [ Ed-Note: I'm afraid this makes no sense to me.  None at all.  I
               don't like the idea of attempting to mash server file
               names together in the client.  I don't understand the
               full, qualified pathname bit.  I don't understand what is
               supposed to happen.  My idea of the FTP model is that it
               is for the client (perhaps with the aid of PWD commands,
               where implemented) to keep track of where it is in the
               server's filesystem.  Note that filesystems need not be
               implemented as any kind of tree, lots of other models are
               possible.  Someone needs to provide lots of guidance, in
               the form of contributed text if this is to remain
               anything like this at all. ]

3.8.3. type=pdir

   If present, the type=pdir entry represents the fully qualified
   pathname of the parent directory of the type=cdir directory.  A CWD
   command with the value should change the user to the parent directory
   of the listed directory.  Client-FTPs should note not all responses
   will include this information.








Hethmon & Elz                                                  [Page 10]


Internet Draft       draft-ietf-ftpext-mlst-00.txt            March 1997


3.8.4. type=dir

   If present, the type=dir entry is the name of a directory.  When
   executed with the current directory in the appropriate place, a CWD
   with this argument should succeed (given the user has the appropriate
   system rights).

3.8.5. type=link

   [ Ed-Note: This might eventually say something not yet written.  What
               that might be is unclear (the whole type might be
               deleted).  It isn't clear to me what a nk" means in the
               FTP context.  If we're talking of symlinks (or aliases,
               or shortcuts, or the various other names they go by in
               various OS's), then we need a way to fetch the value of
               this thing - RETR cannot be it, it must (for sanity) read
               the file linked to, not the link itself.  If this is
               supposed to refer to original unix (hard) links, then I'm
               not sure of the need for this, given that the unique fact
               (next section) provides more useful information.
               Further, it isn't clear which of two unix links to a file
               should be considered to be the type=file and which should
               be considered to be type=link.  Someone who supports the
               existence of this type needs to describe what it means,
               and what operations are supported upon it. ]

3.9. The unique Fact

   The unique fact is used to present a unique identifier for a file or
   directory on a Server-FTP.  This would be expected to be used by
   Server-FTPs whose host system allows things such as symbolic links so
   that the same file may be represented in more than one directory on
   the server.  The value of the unique fact should be considered an
   opaque string for comparison purposes.  The only conclusion that
   should be drawn is that if two different names each have the same
   value for the unique fact, then they refer to the same underlying
   object.

        unique-fact = unique-label "=" token
        unique-label = %h75.6e.69.71.75.65                    ; "unique"

   [ Ed-Note: A definition of token is required ]









Hethmon & Elz                                                  [Page 11]


Internet Draft       draft-ietf-ftpext-mlst-00.txt            March 1997


3.10. The perm Fact

   [ Ed-Note: We need to choose what goes here.  That might be something
               close to one of the following, or something totally
               different. ]

3.10.1. Alternative One (The original)

   The perm fact is used to present the file permissions the user has in
   regard to the listed file.  The value of the fact is a 3 character
   sequence representing read, write, and execute privileges for the
   file or directory as pertaining to the login user.

        perm-fact  = perm-label "=" pvals
        perm-label = %h70.65.72.6d                              ; "perm"
        pvals      = readval writeval executeval
        readval    = "r" / "-"
        writeval   = "w" / "-"
        executeval = "x" / "-"

   The first character specifies the read permission.  The character "r"
   means read is available.  The character "-" means it is not.

   The second character specifies the write permission.  The character
   "w" means write is available while "-" means it is not.

   Likewise the third character specifies the execute permission.  The
   character "x" means execute is available while "-" means it is not.

   A file with read rights allows the User-FTP to retrieve (RETR) the
   file.  If it has executable rights, then the file is considered an
   executable (or runnable) program on the Server-FTP system.  Some
   Server-FTPs may allow the SITE EXEC extension to be used on the
   specified file.  If it has write rights, then the file may be
   appended to using APPE, or written to by STOR.

   A directory with read rights may be the target of a LIST, NLST or
   MLST command.  With execute right, it can be the target of a CWD
   command.  With write rights, new files/directories may be created,
   and existing files/directories deleted or renamed; under usual
   implementations, existing directories may only be deleted if they are
   empty.









Hethmon & Elz                                                  [Page 12]


Internet Draft       draft-ietf-ftpext-mlst-00.txt            March 1997


3.10.2. Alternative Two (Revised)

   The perm fact is used to indicate access rights the current FTP user
   has over the object listed.  Its value is always an unordered
   sequence of alphabetic characters.

        perm-fact  = perm-label "=" pvals
        perm-label = %h70.65.72.6d                              ; "perm"
        pvals      = *ALPHA

   There are eleven permission indicators currently defined.  Many are
   meaningful only when used with a particular type of object.  The
   eleven characters currently defined are:

        a c d e f l m p r w x

   The "a" permission applies to objects of type=file, and indicates
   that the APPE (append) command may be applied to the file named.

   The "c" permission applies to objects of type=dir (and type=pdir,
   type=cdir).  It indicates that files may be created in the directory
   named.  That is, that a STOU command is likely to succeed, and that
   STOR and APPE commands might succeed if the file named did not
   previously exist, but is to be created in the directory object that
   has the "c" permission.  It also indicates that the RNTO command is
   likely to succeed for names in the directory.

   The "d" permission applies to all types.  For type=file it indicates
   that the file may be deleted, that is, that the DELE command may be
   applied to it.  For the directory types it indicates that (some)
   files in the directory may be deleted.

   The "e" permission applies to the directory types.  When set on an
   object of type=dir or type=pdir it indicates that a CWD command
   naming the object should succeed, and the user should be able to
   enter the directory named.  For type=pdir it also indicates that the
   CDUP command should succeed.  For objects of type=cdir this
   permission will normally always be set, and indicates not very much
   at all.

   The "f" permission for objects indicates that the object named may be
   renamed - that is, may be the object of an RNFR command.

   The "l" permission applies to the directory file types, and indicates
   that the listing commands, LIST, NLST, and MLST may be applied to the
   directory in question, or to files in the directory.





Hethmon & Elz                                                  [Page 13]


Internet Draft       draft-ietf-ftpext-mlst-00.txt            March 1997


   The "m" permission applies to directory types, and indicates that the
   MKD command may be used to create a new directory within the
   directory under consideration.

   The "p" permission applies to directory types, and indicates that the
   RMD command may be used to remove (purge) the directory named.

   The "r" permission applies to type=file objects, and indicates that
   the RETR command may be applied to that object.

   The "w" permission applies to type=file objects, and indicates that
   the STOR command may be applied to the object named.

   The "x" permission is slightly unusual, as it does not directly
   relate to any standardized FTP command, yet conveys useful
   information.  This indicator conveys the information that the object
   named, which will be of file type, is an executable image, or program
   file.  Some FTP servers may permit a site specific command (eg:
   "SITE EXEC") to be applied to a file with this permission.

   Note: That a permission bit is set can never imply that the
        appropriate command is guaranteed to work - just that it might.
        Other system specific limitations, such as limitations on
        available space for storing files, may cause an operation to
        fail, where the permission flags may have indicated that it was
        likely to succeed.  The permissions are a guide only.

   Implementation note: The permissions are described here as they apply
        to FTP commands.  They may not map easily into particular
        permissions available on the server's operating system.  Servers
        are expected to synthesize these permission bits from the
        permission information available from operating system.  For
        example, to correctly determine whether the "p" permission bit
        should be set on a directory for a server running on the
        UNIX(TM) operating system, the server should check that the
        directory named is empty, and that the user has write permission
        on both the directory under consideration, and its parent
        directory.

        Some systems may have more specific permissions than those
        listed here, such systems should map those to the flags defined
        as best they are able.  Other systems may have only more broad
        access controls.  They will generally have just a few possible
        permutations of permission flags, however they should attempt to
        correctly represent what is permitted.

   [ Ed-Note: The "x" permission flag may be better handled by using a
               different file type (type=prog, type=xfile, ...) instead.



Hethmon & Elz                                                  [Page 14]


Internet Draft       draft-ietf-ftpext-mlst-00.txt            March 1997


               Opinions? ]

3.11. The lang Fact

   The lang fact describes the natural language of the filename for use
   in display purposes.  Values used here should comply with the
   language registry of IANA.

        lang-fact  = lang-label "=" token
        lang-label = %h6c.61.6e.67                              ; "lang"

   Server-FTP implementations MUST not guess language values.  Language
   values must be determined in an unambiguous way such as filesystem
   tagging of language or by user configuration.

3.12. The size Fact

   The size should always reflect the approximate size of the file.
   This should be as accurate as the server can make it, without going
   to extraordinary lengths, such as reading the entire file.  The size
   is expressed in units of octets.

   Given limitations in some systems, Client-FTP implementations must
   understand this size may not be precise and may change between the
   time of a MLST and RETR operation.

   Clients that need highly accurate size information for some
   particular reason should use the SIZE command as defined in [7].  The
   most common need for this accuracy is likely to be in conjunction
   with the REST command described in the same document.

        size-fact  = size-label "=" 1*DIGIT
        size-label = %h73.69.7a.65                              ; "size"

3.13. The media-type Fact

   The media-type fact represents the IANA media type of the file.  The
   list of values used must follow the guidelines set by the IANA
   registry.

        media-type  = media-label "=" <per IANA guidelines>
        media-label = %h6d.65.64.69.61.2d.74.79.70.65     ; "media-type"

   Server-FTP implementations MUST not guess media type values.  Media
   type values must be determined in an unambiguous way such as
   filesystem tagging of media-type or by user configuration.





Hethmon & Elz                                                  [Page 15]


Internet Draft       draft-ietf-ftpext-mlst-00.txt            March 1997


3.14. The charset Fact

   The charset fact represents the IANA character set name for the
   encoded names in a MLST response.  This is a optional fact.  The
   default character set is UTF-8 unless specified otherwise.  FTP
   implementations SHOULD use UTF-8 if possible to encourage maximum
   interoperability.

3.15. Mandatory minimum reply for MLST

   The mandatory minimum response for MLST when returning a directory
   listing must include an entry for the listed directory (type=cdir).
   This requirement is lifted when returning information about a single
   file.

4. The OPTS Command

   The OPTS (options) command allows a Client-FTP to specify the exact
   set of facts for a Server-FTP to return within a MLST command.  The
   Client-FTP may use the FEAT command to determine the set of facts
   supported by the Server-FTP and then issue the OPTS command to
   specify the set of those facts it wishes to see.  Server-FTPs should
   implement the OPTS command.

   Request Syntax:
        opts            = opts-cmd SP command-name *(command-options) CRLF
        opts-cmd        = "opts"
        command-name    = <any FTP command which allows option setting>
        command-options = <format specified by individual FTP command>

   Response Syntax:
        opts-response   = opts-good / opts-bad
        opts-good       = "200" SP response-message CRLF
        opts-bad        = "451" SP response-message CRLF /
                          "501" SP response-message CRLF

4.1. OPTS parameters for MLST

   For the MLST command, the Client-FTP may specify a list of facts it
   wishes to be returned in all subsequent MLST commands until another
   OPTS MLST command is sent.  The format is specified by:

        mlst-opts = "OPTS" SP ST" SP *facts

   [ Ed-Note: Is the space after "MLST" required if there are no facts?
               ]





Hethmon & Elz                                                  [Page 16]


Internet Draft       draft-ietf-ftpext-mlst-00.txt            March 1997


   By sending the "OPTS MLST" command, the client requests the server to
   include only the facts listed as arguments to the command in
   subsequent output from MLST commands.  Facts not included in the
   "OPTS MLST" command must not be returned by the server.  Facts that
   are included should be returned for each entry returned from the MLST
   command where they apply.  Facts requested that are not supported, or
   which are inappropriate to the file or directory being listed should
   simply be omitted from the MLST output.  This is not an error.

4.2. Using OPTS to select MLST output connection

   [ Ed-Note: This whole section is controversial.  There are some among
               us who believe that use of the control connection for the
               output of the MLST command is positively insane, and
               should simply be abolished, not negotiated... ]

   One of the facts given to the "OPTS MLST" command, but used only in
   this command is one of the special case facts:

        chan-sel      = connect-label "=" connection
        connect-label = %h63.6f.6e.6e.65.63.74.69.6f.6e   ; "connection"
        connection    = %h64.6f.6e.74.72.6f.6c               ; "control"
                        / %h64.61.74.61                         ; "data"

   When the "connection=data" is used on the "OPTS MLST" command, output
   from the MLST command is to be sent on a separate data connection, as
   is done with the LIST command [6].  When the "connection=control" is
   used on the "OPTS MLST" command, output from the MLST command is to
   be sent back as a reply to the MLST command, over the control
   connection, as described in section 3.4.  Where no "OPTS MLST"
   command has been sent, or no "connection=" ct" has been sent, the
   default is for the data connection to be used.

5. Impact On Other FTP Commands

   Along with the introduction of MLST, traditional FTP commands must be
   extended to allow for the use of more than US-ASCII or EBCDIC
   character sets.  In general, the support of MLST requires support for
   arbitrary character sets wherever filenames and directory names are
   allowed.  This applies equally to both arguments given to the
   following commands and to the replies from them.

        CWD
        RETR
        STOR
        APPE
        RNFR
        RNTO



Hethmon & Elz                                                  [Page 17]


Internet Draft       draft-ietf-ftpext-mlst-00.txt            March 1997


        DELE
        RMD
        MKD
        PWD
        STAT

   The arguments to all of these commands should be processed the same
   way that MLST commands and responses are processed with respect to
   handling embedded CRs and NULs.  See section 3.2.

5.1. Impact on Pathnames and Filenames

   The design of MLST requires the Server-FTP to allow concatenation of
   certain elements of a MLST response.  Specifically, a typical
   response would include an element which indicates the current
   directory and one or more elements which are files in the indicated
   directory.  A Server-FTP must be able to accept a simple
   concatenation of these two names even if the underlying operating
   system does not accept a simple concatenation.  The Server-FTP must
   perform any translation of the concatenated name to local
   equivalents.

   [ Ed-Note: I don't believe a word of this.  Directories can be handed
               to the CWD command, and then the file names to RETR
               (etc).  Do we really need this section, and other related
               text? ]

6. Security

   This memo does not yet discuss security.  It is possible that no new
   security concerns are raised in this memo above what already exists
   within the FTP protocol.  However, the working group needs to
   consider this carefully.

7. References

   [1]  Coded Character Set--7-bit American Standard Code for Information
        Interchange, ANSI X3.4-1986.

   [2]  F. Yergeau, "UTF-8, a transformation format of Unicode and ISO
        10646", RFC 2044, Alis Technologies, October 1996.

   [3]  D. Crocker, "Augmented BNF for Syntax Specifications: ABNF",
        Work In Progress <draft-ietf-drums-abnf-02.txt>, Internet
        Mail Consortium, March 1997.

   [4]  W. Curtin, "Internationalization of the File Transfer Protocol",
        Work In Progress <draft-ietf-ftpext-itln-00.txt>, Defense



Hethmon & Elz                                                  [Page 18]


Internet Draft       draft-ietf-ftpext-mlst-00.txt            March 1997


        Information Systems Agency, November 1996.

   [5]  Internet Assigned Numbers Authority. http://www.isi.edu/div7/iana/
        Email: iana@iana.org.

   [6]  J. Postel, J. Reynolds, "File Transfer Protocol (FTP)",
        STD 9 (RFC 959), ISI, October 1985

   [7]  D. Borman, R. Adams, "REST Command and Extensions to FTP",
        Work in progress (draft-ietf-ftpext-restart-00.txt), Berkeley Software
        Design, Inc, UUNET, March, 1997.

Acknowledgements

   The following people have contributed to this document:

        Alex Belits
        D. J. Berstein
        Martin J. Duerst
        Mark Harris
        Alun Jones
        James Matthews
        Keith Moore
        and the entire FTPEXT working group of the IETF.

Editors' Addresses

   Paul Hethmon
   Hethmon Brothers
   2305 Chukar Road
   Knoxville, TN 37923 USA

   Phone: 423-690-8990
   Email: phethmon@hethmon.com


   Robert Elz
   University of Melbourne
   Department of Computer Science
   Parkville, Vic   3052
   Australia

   Email: kre@munnari.OZ.AU








Hethmon & Elz                                                  [Page 19]


Html markup produced by rfcmarkup 1.129d, available from https://tools.ietf.org/tools/rfcmarkup/