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 September 2, 2005.

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.  open, create - prepare a fid for I/O on an existing or new file
    7.4.  stat, wstat - inquire or change file attributes
8.  Security Considerations
9.  Protocol Definition Differences
10.  References
Appendix A.  Acknowledgements
Appendix B.  Copyright
Appendix C.  Lucent Public License Version 1.02
§  Author's Address

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.).

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.

2.1. Overview of Differences

2.1.1. Numeric Versus String IDs

Under Plan 9, 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.

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).

2.1.3. Permission Modes

Plan 9 has a different user security model, so there is no such concept as set-uid or set-gid permissions. There is also no equivilent for the sticky bit. Luckily, Plan 9 has plenty of space in higher permission mode bit space for such extensions.

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.

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.

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.

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[2]

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

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]

3. Protocol Data Types

3.1. Changed Basic Data Types

TODO: cover changed data types in our protocol synopsis

3.2. Changed Structured Data Types

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

4. Changed File Attributes

TODO: discuss changes

5. Versioning

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

6. Error Definitions

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

7. Changed Protocol Operations

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.

7.2. error - return an error

SYNOPSIS

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

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.

7.3. 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]

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).

7.4. 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.

8. Security Considerations

TODO: Talk about specific security considerations of 9P under UNIX, specifically about the different auth models

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 */
};

10. References

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

The original protocol specification is based on the Plan 9 manual pages (specifically section 5), which are covered under the Lucent Public License Version 1.02.

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).

Appendix C. Lucent Public License Version 1.02

==========================================================

Lucent Public License Version 1.02

THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT.

1. DEFINITIONS

"Contribution" means:

a. in the case of Lucent Technologies Inc. ("LUCENT"), the Original Program, and

b. in the case of each Contributor,

i. changes to the Program, and

ii. additions to the Program;

where such changes and/or additions to the Program were added to the Program by such Contributor itself or anyone acting on such Contributor's behalf, and the Contributor explicitly consents, in accordance with Section 3C, to characterization of the changes and/or additions as Contributions.

"Contributor" means LUCENT and any other entity that has Contributed a Contribution to the Program.

"Distributor" means a Recipient that distributes the Program, modifications to the Program, or any part thereof.

"Licensed Patents" mean patent claims licensable by a Contributor which are necessarily infringed by the use or sale of its Contribution alone or when combined with the Program.

"Original Program" means the original version of the software accompanying this Agreement as released by LUCENT, including source code, object code and documentation, if any.

"Program" means the Original Program and Contributions or any part thereof

"Recipient" means anyone who receives the Program under this Agreement, including all Contributors.

2. GRANT OF RIGHTS

a. Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, distribute and sublicense the Contribution of such Contributor, if any, and such derivative works, in source code and object code form.

b. Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free patent license under Licensed Patents to make, use, sell, offer to sell, import and otherwise transfer the Contribution of such Contributor, if any, in source code and object code form. The patent license granted by a Contributor shall also apply to the combination of the Contribution of that Contributor and the Program if, at the time the Contribution is added by the Contributor, such addition of the Contribution causes such combination to be covered by the Licensed Patents. The patent license granted by a Contributor shall not apply to (i) any other combinations which include the Contribution, nor to (ii) Contributions of other Contributors. No hardware per se is licensed hereunder.

c. Recipient understands that although each Contributor grants the licenses to its Contributions set forth herein, no assurances are provided by any Contributor that the Program does not infringe the patent or other intellectual property rights of any other entity. Each Contributor disclaims any liability to Recipient for claims brought by any other entity based on infringement of intellectual property rights or otherwise. As a condition to exercising the rights and licenses granted hereunder, each Recipient hereby assumes sole responsibility to secure any other intellectual property rights needed, if any. For example, if a third party patent license is required to allow Recipient to distribute the Program, it is Recipient's responsibility to acquire that license before distributing the Program.

d. Each Contributor represents that to its knowledge it has sufficient copyright rights in its Contribution, if any, to grant the copyright license set forth in this Agreement.

3. REQUIREMENTS

A. Distributor may choose to distribute the Program in any form under this Agreement or under its own license agreement, provided that:

a. it complies with the terms and conditions of this Agreement;

b. if the Program is distributed in source code or other tangible form, a copy of this Agreement or Distributor's own license agreement is included with each copy of the Program; and

c. if distributed under Distributor's own license agreement, such license agreement:

i. effectively disclaims on behalf of all Contributors all warranties and conditions, express and implied, including warranties or conditions of title and non-infringement, and implied warranties or conditions of merchantability and fitness for a particular purpose;

ii. effectively excludes on behalf of all Contributors all liability for damages, including direct, indirect, special, incidental and consequential damages, such as lost profits; and

iii. states that any provisions which differ from this Agreement are offered by that Contributor alone and not by any other party.

B. Each Distributor must include the following in a conspicuous location in the Program:

Copyright (C) 2003, Lucent Technologies Inc. and others. All Rights Reserved.

C. In addition, each Contributor must identify itself as the originator of its Contribution in a manner that reasonably allows subsequent Recipients to identify the originator of the Contribution. Also, each Contributor must agree that the additions and/or changes are intended to be a Contribution. Once a Contribution is contributed, it may not thereafter be revoked.

4. COMMERCIAL DISTRIBUTION

Commercial distributors of software may accept certain responsibilities with respect to end users, business partners and the like. While this license is intended to facilitate the commercial use of the Program, the Distributor who includes the Program in a commercial product offering should do so in a manner which does not create potential liability for Contributors. Therefore, if a Distributor includes the Program in a commercial product offering, such Distributor ("Commercial Distributor") hereby agrees to defend and indemnify every Contributor ("Indemnified Contributor") against any losses, damages and costs (collectively"Losses") arising from claims, lawsuits and other legal actions brought by a third party against the Indemnified Contributor to the extent caused by the acts or omissions of such Commercial Distributor in connection with its distribution of the Program in a commercial product offering. The obligations in this section do not apply to any claims or Losses relating to any actual or alleged intellectual property infringement. In order to qualify, an Indemnified Contributor must: a) promptly notify the Commercial Distributor in writing of such claim, and b) allow the Commercial Distributor to control, and cooperate with the Commercial Distributor in, the defense and any related settlement negotiations. The Indemnified Contributor may participate in any such claim at its own expense.

For example, a Distributor might include the Program in a commercial product offering, Product X. That Distributor is then a Commercial Distributor. If that Commercial Distributor then makes performance claims, or offers warranties related to Product X, those performance claims and warranties are such Commercial Distributor's responsibility alone. Under this section, the Commercial Distributor would have to defend claims against the Contributors related to those performance claims and warranties, and if a court requires any Contributor to pay any damages as a result, the Commercial Distributor must pay those damages.

5. NO WARRANTY

EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED ON AN"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the appropriateness of using and distributing the Program and assumes all risks associated with its exercise of rights under this Agreement, including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and unavailability or interruption of operations.

6. DISCLAIMER OF LIABILITY

EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

7. EXPORT CONTROL

Recipient agrees that Recipient alone is responsible for compliance with the United States export administration regulations (and the export control laws and regulation of any other countries).

8. GENERAL

If any provision of this Agreement is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this Agreement, and without further action by the parties hereto, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable.

If Recipient institutes patent litigation against a Contributor with respect to a patent applicable to software (including a cross-claim or counterclaim in a lawsuit), then any patent licenses granted by that Contributor to such Recipient under this Agreement shall terminate as of the date such litigation is filed. In addition, if Recipient institutes patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Program itself (excluding combinations of the Program with other software or hardware) infringes such Recipient's patent(s), then such Recipient's rights granted under Section 2(b) shall terminate as of the date such litigation is filed.

All Recipient's rights under this Agreement shall terminate if it fails to comply with any of the material terms or conditions of this Agreement and does not cure such failure in a reasonable period of time after becoming aware of such noncompliance. If all Recipient's rights under this Agreement terminate, Recipient agrees to cease use and distribution of the Program as soon as reasonably practicable. However, Recipient's obligations under this Agreement and any licenses granted by Recipient relating to the Program shall continue and survive.

LUCENT may publish new versions (including revisions) of this Agreement from time to time. Each new version of the Agreement will be given a distinguishing version number. The Program (including Contributions) may always be distributed subject to the version of the Agreement under which it was received. In addition, after a new version of the Agreement is published, Contributor may elect to distribute the Program (including its Contributions) under the new version. No one other than LUCENT has the right to modify this Agreement. Except as expressly stated in Sections 2(a) and 2(b) above, Recipient receives no rights or licenses to the intellectual property of any Contributor under this Agreement, whether expressly, by implication, estoppel or otherwise. All rights in the Program not expressly granted under this Agreement are reserved.

This Agreement is governed by the laws of the State of New York and the intellectual property laws of the United States of America. No party to this Agreement will bring a legal action under this Agreement more than one year after the cause of action arose. Each party waives its rights to a jury trial in any resulting litigation.

Author's Address