                                                                       TOC

   Network Working Group              E. Van Hensbergen
   Internet-Draft                     Plan 9 Fans
   Updates:                           August 17, 2009
   experimental-draft-9P2000-protocol
   (if approved)
   Intended status: Experimental
   Expires: February 18, 2010

                 Plan 9 Remote Resource Protocol Unix Extension
                    experimental-draft-9P2000-unix-extension

  Status of this Memo

   This document is an Internet-Draft and is NOT offered in accordance
   with Section 10 of RFC 2026, and the author does not provide the IETF
   with any rights other than to publish as an Internet-Draft.

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

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

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/ietf/1id-abstracts.txt.

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html.

   This Internet-Draft will expire on February 18, 2010.

  Abstract

   9P is a distributed resource sharing protocol developed as part of the
   Plan 9 research operating system at AT&T Bell Laboratories (now a part
   of Lucent Technologies) by the Computer Science Research Center. It can
   be used to distributed file systems, devices, and application services.
   It was designed as an interface to both local and remote resources,
   making the transition from local to cluster to grid resources
   transparent.

   9P2000.u is a set of extensions to the 9P protocol to better support
   UNIX environments connecting to Plan 9 file servers and UNIX
   environments connecting to other UNIX environments. The extensions
   include support for symbolic links, additional modes, and special files
   (such as pipes and devices). Also included are hints to better support
   mapping of numeric user-ids, group-ids, and error codes.
     __________________________________________________________________

  Table of Contents

   1.  Requirements notation
   2.  Introduction
       2.1.  Overview of Differences
           2.1.1.  Numeric Versus String IDs
           2.1.2.  Error Strings Versus Error Codes
           2.1.3.  Permission Modes
           2.1.4.  Special Files and Links
           2.1.5.  ioctl
           2.1.6.  Extended Attributes
       2.2.  Changed Messages
   3.  Protocol Data Types
       3.1.  Changed Basic Data Types
       3.2.  Changed Structured Data Types
   4.  Changed File Attributes
   5.  Versioning
   6.  Error Definitions
   7.  Changed Protocol Operations
       7.1.  version - negotiate protocol version
       7.2.  error - return an error
       7.3.  auth/attach - messages to establish a connection
       7.4.  open, create - prepare a fid for I/O on an existing or new
   file
       7.5.  stat, wstat - inquire or change file attributes
   8.  Security Considerations
   9.  Protocol Definition Differences
   10.  Normative References
   Appendix A.  Acknowledgements
   Appendix B.  Copyright
   §  Author's Address
     __________________________________________________________________

                                                                       TOC

  1.  Requirements notation

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119] (Bradner, S.,
   “Key words for use in RFCs to Indicate Requirement Levels,”
   March 1997.).
     __________________________________________________________________

                                                                       TOC

  2.  Introduction

   Many modern UNIX systems, including Linux use a virtual file system
   (VFS) layer as a basic level of abstraction for accessing underlying
   implementations. Implementing 9P2000 under Linux is a matter of mapping
   VFS operations to their associated 9P operations. The problem, however,
   is that 9P2000 was designed for a non-UNIX system so there are several
   fundamental differences in the functional semantics provided by 9P.

   To preserve compatibility with these pre-existing features we propose a
   transparent extension to the file system semantics which minimally
   effects the protocol syntax. 9P2000.u is a dialect of 9P2000 negotiated
   in the Tversion/Rversion exchange. If the server agrees to 9P2000.u,
   then the wire protocol that follows is 9P2000 with these changes.
     __________________________________________________________________

                                                                       TOC

  2.1.  Overview of Differences
     __________________________________________________________________

                                                                       TOC

  2.1.1.  Numeric Versus String IDs

   Under Plan 9 [PLAN9] (Lucent Technologies, “Plan 9 Home Page,” .), user
   names as well as groups are represented by strings, while on Unix they
   are represented by unique numbers. This is complicated by Linux making
   it exceedingly difficult to map these numeric identifiers to their
   string values in the kernel. Many of the available UNIX network file
   systems avoid this issue and simply use numeric identifiers over the
   wire, hoping they map to the remote system. NFSv4 has provisions for
   sending string group and user info over the wire and then contacting a
   user-space daemon which attempts to provide a valid mapping.

   9P2000.u provides a dual approach to this problem, changes have been
   made to the protocol to allow for numeric identifiers to be used
   along-side strings. Servers should make every attempt to provide valid
   information for both the numeric and string form of identifiers.
   Clients can then use the available information to best map the
   identifiers to their local environment. Use of extended form string
   user names (e.g. user@domain) as specified in the NFSv4 environment is
   also valid.
     __________________________________________________________________

                                                                       TOC

  2.1.2.  Error Strings Versus Error Codes

   A similar problem exists for error numbers, by default VFS operations
   return error numbers, whereas Plan 9 (and 9P) use error strings to
   describe failure conditions. This problem is further exacerbated by the
   potential for Plan 9 synthetic file servers to return custom error
   strings which may not match any pre-defined set (or pattern) of
   standard error messages.

   Again, our approach is to provide as much information as possible in
   order to help clients properly convey error conditions to
   end-applications and end-users. As such both error strings and error
   codes are conveyed in the 9P2000.u version of the protocol. A suggested
   implementation is that non-standard/unrecognized error strings/codes be
   made available to applications via some mechanism in order to
   communicate application synthetic file system events (via sysfs or
   procfs in Linux, or perhaps via a special extended attribute).
     __________________________________________________________________

                                                                       TOC

  2.1.3.  Permission Modes

   Plan 9 has a different user security model [P9SEC] (Cox, R., Grosse,
   E., Pike, R., Presotto, D., and S. Quinlan, “Security in Plan 9,”
   2002.), so there is no such concept as set-uid or set-gid permissions.
   There is also no equivalent for the sticky bit. Luckily, Plan 9 has
   plenty of space in higher permission mode bit space for such
   extensions.
     __________________________________________________________________

                                                                       TOC

  2.1.4.  Special Files and Links

   One of the unique aspects of the Plan 9 name space is that it is
   dynamic. Users are able to bind files and directories over each other
   in stackable layers similar to union file systems. This aspect of Plan
   9 name spaces has obviated the need for symbolic or hard links.
   Symlinks on a remote UNIX file server will be traversed transparently
   as part of a walk - there is no native ability within Plan 9 to create
   symlinks. This breaks many assumptions for Linux file-systems and many
   existing applications (for example the kernel build creates a symlink
   in the include directory as part of the make process).

   Another unique aspect is that named pipes and devices look just like
   other files in Plan 9, there are no special mode bits and no concept of
   major and minor block numbers.

   To solve both of these problems special mode bits are introduced to
   mark special file types and a variable-length string field is added to
   the file attribute structure which is used to store the additional
   information associated with these special files. In the case of
   symlinks, for instance, the variable length string contains the full
   path target of the symbolic link.
     __________________________________________________________________

                                                                       TOC

  2.1.5.  ioctl

   A VFS function not accounted for in the 9P infrastructure is the ioctl
   command. No attempt has been made at this time to accomodate its
   functionality. Plan 9 has traditionally used elements within a
   synthetic file system to provide for similar functionality, with the
   added benefit of getting transparent network distribution of the
   control path. For such devices/files that still require the use of
   ioctl, gateway synthetic file systems are suggested to provide
   analogous functionality.
     __________________________________________________________________

                                                                       TOC

  2.1.6.  Extended Attributes

   A relatively recent addition to VFS interfaces is the ability to have
   arbitrary key/value pairs added to file meta-data. 9P2000.u doesn't
   have provisions to accomodate this feature, but it may be added in the
   future as more file systems adopt extended attributes.
     __________________________________________________________________

                                                                       TOC

  2.2.  Changed Messages

     size[4] Tversion tag[2] msize[4] version[s]

     size[4] Rversion tag[2] msize[4] version[s]

     size[4] Rerror tag[2] ename[s] errno[4]

     size[4] Tauth tag[2] afid[4] uname[s] aname[s]

     size[4] Rauth tag[2] aqid[13]

     size[4] Tattach tag[2] fid[4] afid[4] uname[s] aname[s]

     size[4] Rattach tag[2] qid[13]

     size[4] Tcreate tag[2] fid[4] name[s] perm[4] mode[1] extension[s]

     size[4] Rcreate tag[2] qid[13] iounit[4]

     size[4] Tstat tag[2] fid[4]

     size[4] Rstat tag[2] stat[n]

     size[4] Twstat tag[2] fid[4] stat[n]

     size[4] Rwstat tag[2]
     __________________________________________________________________

                                                                       TOC

  3.  Protocol Data Types
     __________________________________________________________________

                                                                       TOC

  3.1.  Changed Basic Data Types

   TODO: cover changed data types in our protocol synopsis
     __________________________________________________________________

                                                                       TOC

  3.2.  Changed Structured Data Types

   TODO: cover changed structs (like stat) that the protocol uses
     __________________________________________________________________

                                                                       TOC

  4.  Changed File Attributes

   TODO: discuss changes
     __________________________________________________________________

                                                                       TOC

  5.  Versioning

   TODO: describe protocol versioning in detail (steal from Protocol
   section)
     __________________________________________________________________

                                                                       TOC

  6.  Error Definitions

   TODO: enumerate new standard file system error strings and describe
   possibility of application error strings
     __________________________________________________________________

                                                                       TOC

  7.  Changed Protocol Operations
     __________________________________________________________________

                                                                       TOC

  7.1.  version - negotiate protocol version

   SYNOPSIS

     size[4] Tversion tag[2] msize[4] version[s]

     size[4] Rversion tag[2] msize[4] version[s]

   DESCRIPTION

     Support for 9P2000.u is an optional extension which isn't quite
     covered in the existing version semantics for 9P2000. The original
     protocol specification describes discarding anything after an
     initial period in the version string. We use the information
     following the period as a method for negotiating optional protocol
     extensions.

     If a client desires support for the UNIX extensions, it will send
     the add a .u to the end of the version string (e.g. 9P2000.u). If a
     server is capable of supporting the extension, it will return
     9P2000.u back to the client. If the server is incapable or unwilling
     to support the extensions, it will return the version string without
     the extension specification (e.g. 9P2000).

     Clients should be implemented in such a way to be able to operate
     without the extensions in some degraded form of operation. Specifics
     for how to gracefully degrade operation without specific extensions
     are suggested by this document.
     __________________________________________________________________

                                                                       TOC

  7.2.  error - return an error

   SYNOPSIS

     size[4] Rerror tag[2] ename[s] errno[4]

   DESCRIPTION

     An errno field has been added to the message in order to provide a
     hint of the underlying UNIX error number which caused the error on
     the server. Due to consistency problems of mapping error numbers
     betweeen different versions of UNIX, clients should give preference
     to the error string in attempting to report the error, however, in
     the event that they are unable to map an error string, they may
     return the errno to the application.

     A special errno (ERRUNDEF) is returned by servers who do not wish to
     return raw error numbers. In the event that clients can not
     interpret the error string, they should somehow make the error
     string available to end-application/end-user via dynamic custom
     error codes.
     __________________________________________________________________

                                                                       TOC

  7.3.  auth/attach - messages to establish a connection

   SYNOPSIS

     size[4] Tattach tag[2] fid[4] afid[4] uname[s] aname[s] n_uname[4]

     size[4] Rattach tag[2] qid[13]

     size[4] Tauth tag[2] afid[4] uname[s] aname[s] n_uname[4]

     size[4] Rauth tag[2] aqid[13]

   DESCRIPTION

     A numeric uname field has been added to the attach and auth messages
     in order to provide hints to map a string to a numeric id if such a
     facility is not available. The numeric uname should be given
     preference over the uname string unless n_uname is unspecified (~0).
     __________________________________________________________________

                                                                       TOC

  7.4.  open, create - prepare a fid for I/O on an existing or new file

   SYNOPSIS

     size[4] Tcreate tag[2] fid[4] name[s] perm[4] mode[1] extension[s]

     size[4] Rcreate tag[2] qid[13] iounit[4]

   DESCRIPTION

     The most signifigant change to the create operation is the new
     permission modes which allow for creation of special files. In
     addition to creating directories with DMDIR, 9P2000.u allows the
     creation of symlinks (DMSYMLINK), devices (DMDEVICE), named pipes
     (DMNAMEPIPE), and sockets (DMSOCKET). extension[s] is a string
     describing special files, depending on the mode bit. For DSYMLINK
     files, the string is the target of the link. For DMDEVICE files, the
     string is "b 1 2" for a block device with major 1, minor 2. For
     normal files, this string is empty.
     __________________________________________________________________

                                                                       TOC

  7.5.  stat, wstat - inquire or change file attributes

   SYNOPSIS

     size[4] Tstat tag[2] fid[4]

     size[4] Rstat tag[2] stat[n]

     size[4] Twstat tag[2] fid[4] stat[n]

     size[4] Rwstat tag[2]

   DESCRIPTION

     There are four new fields in the stat structure supporting 9P2000
     extensions - as well as new qid.type bits and mode bits.

   size[2]
          total byte count of the following data

   type[2]
          for kernel use

   dev[4]
          for kernel use

   qid.type[1]
          the type of the file (directory, etc.), represented as a bit
          vector corresponding to the high 8 bits of the file's mode word.

   qid.vers[4]
          version number for given path

   qid.path[8]
          the file server's unique identification for the file

   mode[4]
          permissions and flags

   atime[4]
          last access time

   mtime[4]
          last modification time

   length[8]
          length of file in bytes

   name[ s ]
          file name; must be / if the file is the root directory of the
          server

   uid[ s ]
          owner name

   gid[ s ]
          group name

   muid[ s ]
          name of the user who last modified the file

   extension[ s ]
          For use by the UNIX extension to store data about special files
          (links, devices, pipes, etc.)

   n_uid[4]
          numeric id of the user who owns the file

   n_gid[4]
          numeric id of the group associated with the file

   n_muid[4]
          numeric id of the user who last modified the file

     The n_uid, n_gid, and n_muid are numeric hints that clients may use
     to map numeric ids when a string to numeric id mapping facility is
     not available.

     extension[s] is a string describing special files, depending on the
     mode bit. For DSYMLINK files, the string is the target of the link.
     For DMDEVICE files, the string is "b 1 2" for a block device with
     major 1, minor 2. For normal files, this string is empty.
     __________________________________________________________________

                                                                       TOC

  8.  Security Considerations

   TODO: Talk about specific security considerations of 9P under UNIX,
   specifically about the different auth models [P9SEC] (Cox, R., Grosse,
   E., Pike, R., Presotto, D., and S. Quinlan, “Security in Plan 9,”
   2002.)
     __________________________________________________________________

                                                                       TOC

  9.  Protocol Definition Differences

/* permissions */
enum {
        DMDIR =            0x80000000,
        DMAPPEND =         0x40000000,
        DMEXCL =           0x20000000,
        DMMOUNT =          0x10000000,
        DMAUTH =           0x08000000,
        DMTMP =            0x04000000,
        DMSYMLINK =        0x02000000,
        /* 9P2000.u extensions */
        DMDEVICE =         0x00800000,
        DMNAMEDPIPE =      0x00200000,
        DMSOCKET =         0x00100000,
        DMSETUID =         0x00080000,
        DMSETGID =         0x00040000,
};

/* qid.types */
enum {
        QTDIR =            0x80,
        QTAPPEND =         0x40,
        QTEXCL =           0x20,
        QTMOUNT =          0x10,
        QTAUTH =           0x08,
        QTTMP =            0x04,
        QTLINK =           0x02,
        QTFILE =           0x00,
};
struct v9fs_stat {
        uint16_t size;
        uint16_t type;
        uint32_t dev;
        struct v9fs_qid qid;
        uint32_t mode;
        uint32_t atime;
        uint32_t mtime;
        uint64_t length;
        char *name;
        char *uid;
        char *gid;
        char *muid;
/* 9p2000.u extensions */
        char *extension;
        uint32_t n_uid;
        uint32_t n_gid;
        uint32_t n_muid;

        char data[0];
};

struct Rerror {
        char *error;
        uint32_t errno;         /* 9p2000.u extension */
};
     __________________________________________________________________

                                                                       TOC

  10. Normative References

   [P9SEC] Cox, R., Grosse, E., Pike, R., Presotto, D., and S. Quinlan,
   “Security in Plan 9,” Proceedings of the Usenix Security Symposium,
   2002.
   [PLAN9] Lucent Technologies, “Plan 9 Home Page.”
   [RFC2119] Bradner, S., “Key words for use in RFCs to Indicate
   Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML).
     __________________________________________________________________

                                                                       TOC

  Appendix A.  Acknowledgements

   The 9P2000.u protocol extensions evolved out of contributions from a
   number of people including:

     Russ Cox

     Lachester Ionkov

     Ron Minnich

     Andrey Mirtchoviski

     Rob Pike

     Eric Van Hensbergen

     Uriel (Contentious Objector)

   The 9P protocol was the result of work done by the Computing Science
   Research Center of AT&T Bell Labs (now a part of Lucent Technologies)
   and in particular:

     Rob Pike

     Dave Presotto

     Sape Mullender

     Ken Thompson

     Russ Cox
     __________________________________________________________________

                                                                       TOC

  Appendix B.  Copyright

   This specification is derrived from the Plan 9 Documentation and Manual
   Pages. The source material is Copyright (C) 2003, Lucent Technologies
   Inc. and others. All Rights Reserved.

   Extensions to the original source material are Copyright (C) 2005, the
   authors of this document (as specified in Authors List in the
   References section).
     __________________________________________________________________

                                                                       TOC

  Author's Address

           Eric Van Hensbergen
           Plan 9 Fans
   Email:  9fans@cse.psu.edu
     URI:  http://plan9.bell-labs.com/plan9
