Documentation/filesystems/9p.txt

   1                     v9fs: Plan 9 Resource Sharing for Linux
   2                     =======================================
   3
   4 ABOUT
   5 =====
   6
   7 v9fs is a Unix implementation of the Plan 9 9p remote filesystem protocol.
   8
   9 This software was originally developed by Ron Minnich <rminnich@sandia.gov>
  10 and Maya Gokhale.  Additional development by Greg Watson
  11 <gwatson@lanl.gov> and most recently Eric Van Hensbergen
  12 <ericvh@gmail.com>, Latchesar Ionkov <lucho@ionkov.net> and Russ Cox
  13 <rsc@swtch.com>.
  14
  15 The best detailed explanation of the Linux implementation and applications of
  16 the 9p client is available in the form of a USENIX paper:
  17    http://www.usenix.org/events/usenix05/tech/freenix/hensbergen.html
  18
  19 Other applications are described in the following papers:
  20         * XCPU & Clustering
  21                 http://xcpu.org/papers/xcpu-talk.pdf
  22         * KVMFS: control file system for KVM
  23                 http://xcpu.org/papers/kvmfs.pdf
  24         * CellFS: A New Programming Model for the Cell BE
  25                 http://xcpu.org/papers/cellfs-talk.pdf
  26         * PROSE I/O: Using 9p to enable Application Partitions
  27                 http://plan9.escet.urjc.es/iwp9/cready/PROSE_iwp9_2006.pdf
  28         * VirtFS: A Virtualization Aware File System pass-through
  29                 http://goo.gl/3WPDg
  30
  31 USAGE
  32 =====
  33
  34 For remote file server:
  35
  36         mount -t 9p 10.10.1.2 /mnt/9
  37
  38 For Plan 9 From User Space applications (http://swtch.com/plan9)
  39
  40         mount -t 9p `namespace`/acme /mnt/9 -o trans=unix,uname=$USER
  41
  42 For server running on QEMU host with virtio transport:
  43
  44         mount -t 9p -o trans=virtio <mount_tag> /mnt/9
  45
  46 where mount_tag is the tag associated by the server to each of the exported
  47 mount points. Each 9P export is seen by the client as a virtio device with an
  48 associated "mount_tag" property. Available mount tags can be
  49 seen by reading /sys/bus/virtio/drivers/9pnet_virtio/virtio<n>/mount_tag files.
  50
  51 OPTIONS
  52 =======
  53
  54   trans=name    select an alternative transport.  Valid options are
  55                 currently:
  56                         unix    - specifying a named pipe mount point
  57                         tcp     - specifying a normal TCP/IP connection
  58                         fd      - used passed file descriptors for connection
  59                                 (see rfdno and wfdno)
  60                         virtio  - connect to the next virtio channel available
  61                                 (from QEMU with trans_virtio module)
  62                         rdma    - connect to a specified RDMA channel
  63
  64   uname=name    user name to attempt mount as on the remote server.  The
  65                 server may override or ignore this value.  Certain user
  66                 names may require authentication.
  67
  68   aname=name    aname specifies the file tree to access when the server is
  69                 offering several exported file systems.
  70
  71   cache=mode    specifies a caching policy.  By default, no caches are used.
  72                         loose = no attempts are made at consistency,
  73                                 intended for exclusive, read-only mounts
  74                         fscache = use FS-Cache for a persistent, read-only
  75                                 cache backend.
  76
  77   debug=n       specifies debug level.  The debug level is a bitmask.
  78                         0x01  = display verbose error messages
  79                         0x02  = developer debug (DEBUG_CURRENT)
  80                         0x04  = display 9p trace
  81                         0x08  = display VFS trace
  82                         0x10  = display Marshalling debug
  83                         0x20  = display RPC debug
  84                         0x40  = display transport debug
  85                         0x80  = display allocation debug
  86                         0x100 = display protocol message debug
  87                         0x200 = display Fid debug
  88                         0x400 = display packet debug
  89                         0x800 = display fscache tracing debug
  90
  91   rfdno=n       the file descriptor for reading with trans=fd
  92
  93   wfdno=n       the file descriptor for writing with trans=fd
  94
  95   msize=n       the number of bytes to use for 9p packet payload
  96
  97   port=n        port to connect to on the remote server
  98
  99   noextend      force legacy mode (no 9p2000.u or 9p2000.L semantics)
 100
 101   version=name  Select 9P protocol version. Valid options are:
 102                         9p2000          - Legacy mode (same as noextend)
 103                         9p2000.u        - Use 9P2000.u protocol
 104                         9p2000.L        - Use 9P2000.L protocol
 105
 106   dfltuid       attempt to mount as a particular uid
 107
 108   dfltgid       attempt to mount with a particular gid
 109
 110   afid          security channel - used by Plan 9 authentication protocols
 111
 112   nodevmap      do not map special files - represent them as normal files.
 113                 This can be used to share devices/named pipes/sockets between
 114                 hosts.  This functionality will be expanded in later versions.
 115
 116   access        there are four access modes.
 117                         user  = if a user tries to access a file on v9fs
 118                                 filesystem for the first time, v9fs sends an
 119                                 attach command (Tattach) for that user.
 120                                 This is the default mode.
 121                         <uid> = allows only user with uid=<uid> to access
 122                                 the files on the mounted filesystem
 123                         any   = v9fs does single attach and performs all
 124                                 operations as one user
 125                         client = ACL based access check on the 9p client
 126                                  side for access validation
 127
 128   cachetag      cache tag to use the specified persistent cache.
 129                 cache tags for existing cache sessions can be listed at
 130                 /sys/fs/9p/caches. (applies only to cache=fscache)
 131
 132 RESOURCES
 133 =========
 134
 135 Protocol specifications are maintained on github:
 136 http://ericvh.github.com/9p-rfc/
 137
 138 9p client and server implementations are listed on
 139 http://9p.cat-v.org/implementations
 140
 141 A 9p2000.L server is being developed by LLNL and can be found
 142 at http://code.google.com/p/diod/
 143
 144 There are user and developer mailing lists available through the v9fs project
 145 on sourceforge (http://sourceforge.net/projects/v9fs).
 146
 147 News and other information is maintained on a Wiki.
 148 (http://sf.net/apps/mediawiki/v9fs/index.php).
 149
 150 Bug reports may be issued through the kernel.org bugzilla
 151 (http://bugzilla.kernel.org)
 152
 153 For more information on the Plan 9 Operating System check out
 154 http://plan9.bell-labs.com/plan9
 155
 156 For information on Plan 9 from User Space (Plan 9 applications and libraries
 157 ported to Linux/BSD/OSX/etc) check out http://swtch.com/plan9
 158
 159
 160 STATUS
 161 ======
 162
 163 The 2.6 kernel support is working on PPC and x86.
 164
 165 PLEASE USE THE KERNEL BUGZILLA TO REPORT PROBLEMS. (http://bugzilla.kernel.org)
 166