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                 The mode can be specified as a bitmask or by using one of the
  82                 preexisting common 'shortcuts'.
  83                 The bitmask is described below: (unspecified bits are reserved)
  84
  85                         ==========  ====================================================
  86                         0b00000000  all caches disabled, mmap disabled
  87                         0b00000001  file caches enabled
  88                         0b00000010  meta-data caches enabled
  89                         0b00000100  writeback behavior (as opposed to writethrough)
  90                         0b00001000  loose caches (no explicit consistency with server)
  91                         0b10000000  fscache enabled for persistent caching
  92                         ==========  ====================================================
  93
  94                 The current shortcuts and their associated bitmask are:
  95
  96                         =========   ====================================================
  97                         none        0b00000000 (no caching)
  98                         readahead   0b00000001 (only read-ahead file caching)
  99                         mmap        0b00000101 (read-ahead + writeback file cache)
 100                         loose       0b00001111 (non-coherent file and meta-data caches)
 101                         fscache     0b10001111 (persistent loose cache)
 102                         =========   ====================================================
 103
 104                 NOTE: only these shortcuts are tested modes of operation at the
 105                 moment, so using other combinations of bit-patterns is not
 106                 known to work.  Work on better cache support is in progress.
 107
 108                 IMPORTANT: loose caches (and by extension at the moment fscache)
 109                 do not necessarily validate cached values on the server.  In other
 110                 words changes on the server are not guaranteed to be reflected
 111                 on the client system.  Only use this mode of operation if you
 112                 have an exclusive mount and the server will modify the filesystem
 113                 underneath you.
 114
 115   debug=n       specifies debug level.  The debug level is a bitmask.
 116
 117                         =====   ================================
 118                         0x01    display verbose error messages
 119                         0x02    developer debug (DEBUG_CURRENT)
 120                         0x04    display 9p trace
 121                         0x08    display VFS trace
 122                         0x10    display Marshalling debug
 123                         0x20    display RPC debug
 124                         0x40    display transport debug
 125                         0x80    display allocation debug
 126                         0x100   display protocol message debug
 127                         0x200   display Fid debug
 128                         0x400   display packet debug
 129                         0x800   display fscache tracing debug
 130                         =====   ================================
 131
 132   rfdno=n       the file descriptor for reading with trans=fd
 133
 134   wfdno=n       the file descriptor for writing with trans=fd
 135
 136   msize=n       the number of bytes to use for 9p packet payload
 137
 138   port=n        port to connect to on the remote server
 139
 140   noextend      force legacy mode (no 9p2000.u or 9p2000.L semantics)
 141
 142   version=name  Select 9P protocol version. Valid options are:
 143
 144                         ========        ==============================
 145                         9p2000          Legacy mode (same as noextend)
 146                         9p2000.u        Use 9P2000.u protocol
 147                         9p2000.L        Use 9P2000.L protocol
 148                         ========        ==============================
 149
 150   dfltuid       attempt to mount as a particular uid
 151
 152   dfltgid       attempt to mount with a particular gid
 153
 154   afid          security channel - used by Plan 9 authentication protocols
 155
 156   nodevmap      do not map special files - represent them as normal files.
 157                 This can be used to share devices/named pipes/sockets between
 158                 hosts.  This functionality will be expanded in later versions.
 159
 160   directio      bypass page cache on all read/write operations
 161
 162   ignoreqv      ignore qid.version==0 as a marker to ignore cache
 163
 164   noxattr       do not offer xattr functions on this mount.
 165
 166   access        there are four access modes.
 167                         user
 168                                 if a user tries to access a file on v9fs
 169                                 filesystem for the first time, v9fs sends an
 170                                 attach command (Tattach) for that user.
 171                                 This is the default mode.
 172                         <uid>
 173                                 allows only user with uid=<uid> to access
 174                                 the files on the mounted filesystem
 175                         any
 176                                 v9fs does single attach and performs all
 177                                 operations as one user
 178                         clien
 179                                  ACL based access check on the 9p client
 180                                  side for access validation
 181
 182   cachetag      cache tag to use the specified persistent cache.
 183                 cache tags for existing cache sessions can be listed at
 184                 /sys/fs/9p/caches. (applies only to cache=fscache)
 185   ============= ===============================================================
 186
 187 Behavior
 188 ========
 189
 190 This section aims at describing 9p 'quirks' that can be different
 191 from a local filesystem behaviors.
 192
 193  - Setting O_NONBLOCK on a file will make client reads return as early
 194    as the server returns some data instead of trying to fill the read
 195    buffer with the requested amount of bytes or end of file is reached.
 196
 197 Resources
 198 =========
 199
 200 Protocol specifications are maintained on github:
 201 http://ericvh.github.com/9p-rfc/
 202
 203 9p client and server implementations are listed on
 204 http://9p.cat-v.org/implementations
 205
 206 A 9p2000.L server is being developed by LLNL and can be found
 207 at http://code.google.com/p/diod/
 208
 209 There are user and developer mailing lists available through the v9fs project
 210 on sourceforge (http://sourceforge.net/projects/v9fs).
 211
 212 News and other information is maintained on a Wiki.
 213 (http://sf.net/apps/mediawiki/v9fs/index.php).
 214
 215 Bug reports are best issued via the mailing list.
 216
 217 For more information on the Plan 9 Operating System check out
 218 http://plan9.bell-labs.com/plan9
 219
 220 For information on Plan 9 from User Space (Plan 9 applications and libraries
 221 ported to Linux/BSD/OSX/etc) check out https://9fans.github.io/plan9port/