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           https://kernel.org/doc/ols/2010/ols2010-pages-109-120.pdf
  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 generated 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 USBG Usage
  57 ==========
  58
  59 To mount a 9p FS on a USB Host accessible via the gadget at runtime::
  60
  61         mount -t 9p -o trans=usbg,aname=/path/to/fs <device> /mnt/9
  62
  63 To mount a 9p FS on a USB Host accessible via the gadget as root filesystem::
  64
  65         root=<device> rootfstype=9p rootflags=trans=usbg,cache=loose,uname=root,access=0,dfltuid=0,dfltgid=0,aname=/path/to/rootfs
  66
  67 where <device> is the tag associated by the usb gadget transport.
  68 It is defined by the configfs instance name.
  69
  70 USBG Example
  71 ============
  72
  73 The USB host exports a filesystem, while the gadget on the USB device
  74 side makes it mountable.
  75
  76 Diod (9pfs server) and the forwarder are on the development host, where
  77 the root filesystem is actually stored. The gadget is initialized during
  78 boot (or later) on the embedded board. Then the forwarder will find it
  79 on the USB bus and start forwarding requests.
  80
  81 In this case the 9p requests come from the device and are handled by the
  82 host. The reason is that USB device ports are normally not available on
  83 PCs, so a connection in the other direction would not work.
  84
  85 When using the usbg transport, for now there is no native usb host
  86 service capable to handle the requests from the gadget driver. For
  87 this we have to use the extra python tool p9_fwd.py from tools/usb.
  88
  89 Just start the 9pfs capable network server like diod/nfs-ganesha e.g.::
  90
  91         $ diod -f -n -d 0 -S -l 0.0.0.0:9999 -e $PWD
  92
  93 Optionaly scan your bus if there are more then one usbg gadgets to find their path::
  94
  95         $ python $kernel_dir/tools/usb/p9_fwd.py list
  96
  97         Bus | Addr | Manufacturer     | Product          | ID        | Path
  98         --- | ---- | ---------------- | ---------------- | --------- | ----
  99           2 |   67 | unknown          | unknown          | 1d6b:0109 | 2-1.1.2
 100           2 |   68 | unknown          | unknown          | 1d6b:0109 | 2-1.1.3
 101
 102 Then start the python transport::
 103
 104         $ python $kernel_dir/tools/usb/p9_fwd.py --path 2-1.1.2 connect -p 9999
 105
 106 After that the gadget driver can be used as described above.
 107
 108 One use-case is to use it as an alternative to NFS root booting during
 109 the development of embedded Linux devices.
 110
 111 Options
 112 =======
 113
 114   ============= ===============================================================
 115   trans=name    select an alternative transport.  Valid options are
 116                 currently:
 117
 118                         ========  ============================================
 119                         unix      specifying a named pipe mount point
 120                         tcp       specifying a normal TCP/IP connection
 121                         fd        used passed file descriptors for connection
 122                                   (see rfdno and wfdno)
 123                         virtio    connect to the next virtio channel available
 124                                   (from QEMU with trans_virtio module)
 125                         rdma      connect to a specified RDMA channel
 126                         usbg      connect to a specified usb gadget channel
 127                         ========  ============================================
 128
 129   uname=name    user name to attempt mount as on the remote server.  The
 130                 server may override or ignore this value.  Certain user
 131                 names may require authentication.
 132
 133   aname=name    aname specifies the file tree to access when the server is
 134                 offering several exported file systems.
 135
 136   cache=mode    specifies a caching policy.  By default, no caches are used.
 137                 The mode can be specified as a bitmask or by using one of the
 138                 preexisting common 'shortcuts'.
 139                 The bitmask is described below: (unspecified bits are reserved)
 140
 141                         ==========  ====================================================
 142                         0b00000000  all caches disabled, mmap disabled
 143                         0b00000001  file caches enabled
 144                         0b00000010  meta-data caches enabled
 145                         0b00000100  writeback behavior (as opposed to writethrough)
 146                         0b00001000  loose caches (no explicit consistency with server)
 147                         0b10000000  fscache enabled for persistent caching
 148                         ==========  ====================================================
 149
 150                 The current shortcuts and their associated bitmask are:
 151
 152                         =========   ====================================================
 153                         none        0b00000000 (no caching)
 154                         readahead   0b00000001 (only read-ahead file caching)
 155                         mmap        0b00000101 (read-ahead + writeback file cache)
 156                         loose       0b00001111 (non-coherent file and meta-data caches)
 157                         fscache     0b10001111 (persistent loose cache)
 158                         =========   ====================================================
 159
 160                 NOTE: only these shortcuts are tested modes of operation at the
 161                 moment, so using other combinations of bit-patterns is not
 162                 known to work.  Work on better cache support is in progress.
 163
 164                 IMPORTANT: loose caches (and by extension at the moment fscache)
 165                 do not necessarily validate cached values on the server.  In other
 166                 words changes on the server are not guaranteed to be reflected
 167                 on the client system.  Only use this mode of operation if you
 168                 have an exclusive mount and the server will modify the filesystem
 169                 underneath you.
 170
 171   debug=n       specifies debug level.  The debug level is a bitmask.
 172
 173                         =====   ================================
 174                         0x01    display verbose error messages
 175                         0x02    developer debug (DEBUG_CURRENT)
 176                         0x04    display 9p trace
 177                         0x08    display VFS trace
 178                         0x10    display Marshalling debug
 179                         0x20    display RPC debug
 180                         0x40    display transport debug
 181                         0x80    display allocation debug
 182                         0x100   display protocol message debug
 183                         0x200   display Fid debug
 184                         0x400   display packet debug
 185                         0x800   display fscache tracing debug
 186                         =====   ================================
 187
 188   rfdno=n       the file descriptor for reading with trans=fd
 189
 190   wfdno=n       the file descriptor for writing with trans=fd
 191
 192   msize=n       the number of bytes to use for 9p packet payload
 193
 194   port=n        port to connect to on the remote server
 195
 196   noextend      force legacy mode (no 9p2000.u or 9p2000.L semantics)
 197
 198   version=name  Select 9P protocol version. Valid options are:
 199
 200                         ========        ==============================
 201                         9p2000          Legacy mode (same as noextend)
 202                         9p2000.u        Use 9P2000.u protocol
 203                         9p2000.L        Use 9P2000.L protocol
 204                         ========        ==============================
 205
 206   dfltuid       attempt to mount as a particular uid
 207
 208   dfltgid       attempt to mount with a particular gid
 209
 210   afid          security channel - used by Plan 9 authentication protocols
 211
 212   nodevmap      do not map special files - represent them as normal files.
 213                 This can be used to share devices/named pipes/sockets between
 214                 hosts.  This functionality will be expanded in later versions.
 215
 216   directio      bypass page cache on all read/write operations
 217
 218   ignoreqv      ignore qid.version==0 as a marker to ignore cache
 219
 220   noxattr       do not offer xattr functions on this mount.
 221
 222   access        there are four access modes.
 223                         user
 224                                 if a user tries to access a file on v9fs
 225                                 filesystem for the first time, v9fs sends an
 226                                 attach command (Tattach) for that user.
 227                                 This is the default mode.
 228                         <uid>
 229                                 allows only user with uid=<uid> to access
 230                                 the files on the mounted filesystem
 231                         any
 232                                 v9fs does single attach and performs all
 233                                 operations as one user
 234                         clien
 235                                  ACL based access check on the 9p client
 236                                  side for access validation
 237
 238   cachetag      cache tag to use the specified persistent cache.
 239                 cache tags for existing cache sessions can be listed at
 240                 /sys/fs/9p/caches. (applies only to cache=fscache)
 241   ============= ===============================================================
 242
 243 Behavior
 244 ========
 245
 246 This section aims at describing 9p 'quirks' that can be different
 247 from a local filesystem behaviors.
 248
 249  - Setting O_NONBLOCK on a file will make client reads return as early
 250    as the server returns some data instead of trying to fill the read
 251    buffer with the requested amount of bytes or end of file is reached.
 252
 253 Resources
 254 =========
 255
 256 Protocol specifications are maintained on github:
 257 http://ericvh.github.com/9p-rfc/
 258
 259 9p client and server implementations are listed on
 260 http://9p.cat-v.org/implementations
 261
 262 A 9p2000.L server is being developed by LLNL and can be found
 263 at http://code.google.com/p/diod/
 264
 265 There are user and developer mailing lists available through the v9fs project
 266 on sourceforge (http://sourceforge.net/projects/v9fs).
 267
 268 News and other information is maintained on a Wiki.
 269 (http://sf.net/apps/mediawiki/v9fs/index.php).
 270
 271 Bug reports are best issued via the mailing list.
 272
 273 For more information on the Plan 9 Operating System check out
 274 http://plan9.bell-labs.com/plan9
 275
 276 For information on Plan 9 from User Space (Plan 9 applications and libraries
 277 ported to Linux/BSD/OSX/etc) check out https://9fans.github.io/plan9port/