linux/Documentation/filesystems/9p.rst
<<
>>
Prefs
   1.. SPDX-License-Identifier: GPL-2.0
   2
   3=======================================
   4v9fs: Plan 9 Resource Sharing for Linux
   5=======================================
   6
   7About
   8=====
   9
  10v9fs is a Unix implementation of the Plan 9 9p remote filesystem protocol.
  11
  12This software was originally developed by Ron Minnich <rminnich@sandia.gov>
  13and 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
  18The best detailed explanation of the Linux implementation and applications of
  19the 9p client is available in the form of a USENIX paper:
  20
  21   https://www.usenix.org/events/usenix05/tech/freenix/hensbergen.html
  22
  23Other 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
  36Usage
  37=====
  38
  39For remote file server::
  40
  41        mount -t 9p 10.10.1.2 /mnt/9
  42
  43For 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
  47For server running on QEMU host with virtio transport::
  48
  49        mount -t 9p -o trans=virtio <mount_tag> /mnt/9
  50
  51where mount_tag is the tag associated by the server to each of the exported
  52mount points. Each 9P export is seen by the client as a virtio device with an
  53associated "mount_tag" property. Available mount tags can be
  54seen by reading /sys/bus/virtio/drivers/9pnet_virtio/virtio<n>/mount_tag files.
  55
  56Options
  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
 161Behavior
 162========
 163
 164This section aims at describing 9p 'quirks' that can be different
 165from 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
 171Resources
 172=========
 173
 174Protocol specifications are maintained on github:
 175http://ericvh.github.com/9p-rfc/
 176
 1779p client and server implementations are listed on
 178http://9p.cat-v.org/implementations
 179
 180A 9p2000.L server is being developed by LLNL and can be found
 181at http://code.google.com/p/diod/
 182
 183There are user and developer mailing lists available through the v9fs project
 184on sourceforge (http://sourceforge.net/projects/v9fs).
 185
 186News and other information is maintained on a Wiki.
 187(http://sf.net/apps/mediawiki/v9fs/index.php).
 188
 189Bug reports are best issued via the mailing list.
 190
 191For more information on the Plan 9 Operating System check out
 192http://plan9.bell-labs.com/plan9
 193
 194For information on Plan 9 from User Space (Plan 9 applications and libraries
 195ported to Linux/BSD/OSX/etc) check out https://9fans.github.io/plan9port/
 196