Documentation/filesystems/9p.rst

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