9p.rst (6777B)
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/