0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 =======================================
0004 v9fs: Plan 9 Resource Sharing for Linux
0005 =======================================
0006
0007 About
0008 =====
0009
0010 v9fs is a Unix implementation of the Plan 9 9p remote filesystem protocol.
0011
0012 This software was originally developed by Ron Minnich <rminnich@sandia.gov>
0013 and Maya Gokhale. Additional development by Greg Watson
0014 <gwatson@lanl.gov> and most recently Eric Van Hensbergen
0015 <ericvh@gmail.com>, Latchesar Ionkov <lucho@ionkov.net> and Russ Cox
0016 <rsc@swtch.com>.
0017
0018 The best detailed explanation of the Linux implementation and applications of
0019 the 9p client is available in the form of a USENIX paper:
0020
0021 https://www.usenix.org/events/usenix05/tech/freenix/hensbergen.html
0022
0023 Other applications are described in the following papers:
0024
0025 * XCPU & Clustering
0026 http://xcpu.org/papers/xcpu-talk.pdf
0027 * KVMFS: control file system for KVM
0028 http://xcpu.org/papers/kvmfs.pdf
0029 * CellFS: A New Programming Model for the Cell BE
0030 http://xcpu.org/papers/cellfs-talk.pdf
0031 * PROSE I/O: Using 9p to enable Application Partitions
0032 http://plan9.escet.urjc.es/iwp9/cready/PROSE_iwp9_2006.pdf
0033 * VirtFS: A Virtualization Aware File System pass-through
0034 http://goo.gl/3WPDg
0035
0036 Usage
0037 =====
0038
0039 For remote file server::
0040
0041 mount -t 9p 10.10.1.2 /mnt/9
0042
0043 For Plan 9 From User Space applications (http://swtch.com/plan9)::
0044
0045 mount -t 9p `namespace`/acme /mnt/9 -o trans=unix,uname=$USER
0046
0047 For server running on QEMU host with virtio transport::
0048
0049 mount -t 9p -o trans=virtio <mount_tag> /mnt/9
0050
0051 where mount_tag is the tag associated by the server to each of the exported
0052 mount points. Each 9P export is seen by the client as a virtio device with an
0053 associated "mount_tag" property. Available mount tags can be
0054 seen by reading /sys/bus/virtio/drivers/9pnet_virtio/virtio<n>/mount_tag files.
0055
0056 Options
0057 =======
0058
0059 ============= ===============================================================
0060 trans=name select an alternative transport. Valid options are
0061 currently:
0062
0063 ======== ============================================
0064 unix specifying a named pipe mount point
0065 tcp specifying a normal TCP/IP connection
0066 fd used passed file descriptors for connection
0067 (see rfdno and wfdno)
0068 virtio connect to the next virtio channel available
0069 (from QEMU with trans_virtio module)
0070 rdma connect to a specified RDMA channel
0071 ======== ============================================
0072
0073 uname=name user name to attempt mount as on the remote server. The
0074 server may override or ignore this value. Certain user
0075 names may require authentication.
0076
0077 aname=name aname specifies the file tree to access when the server is
0078 offering several exported file systems.
0079
0080 cache=mode specifies a caching policy. By default, no caches are used.
0081
0082 none
0083 default no cache policy, metadata and data
0084 alike are synchronous.
0085 loose
0086 no attempts are made at consistency,
0087 intended for exclusive, read-only mounts
0088 fscache
0089 use FS-Cache for a persistent, read-only
0090 cache backend.
0091 mmap
0092 minimal cache that is only used for read-write
0093 mmap. Northing else is cached, like cache=none
0094
0095 debug=n specifies debug level. The debug level is a bitmask.
0096
0097 ===== ================================
0098 0x01 display verbose error messages
0099 0x02 developer debug (DEBUG_CURRENT)
0100 0x04 display 9p trace
0101 0x08 display VFS trace
0102 0x10 display Marshalling debug
0103 0x20 display RPC debug
0104 0x40 display transport debug
0105 0x80 display allocation debug
0106 0x100 display protocol message debug
0107 0x200 display Fid debug
0108 0x400 display packet debug
0109 0x800 display fscache tracing debug
0110 ===== ================================
0111
0112 rfdno=n the file descriptor for reading with trans=fd
0113
0114 wfdno=n the file descriptor for writing with trans=fd
0115
0116 msize=n the number of bytes to use for 9p packet payload
0117
0118 port=n port to connect to on the remote server
0119
0120 noextend force legacy mode (no 9p2000.u or 9p2000.L semantics)
0121
0122 version=name Select 9P protocol version. Valid options are:
0123
0124 ======== ==============================
0125 9p2000 Legacy mode (same as noextend)
0126 9p2000.u Use 9P2000.u protocol
0127 9p2000.L Use 9P2000.L protocol
0128 ======== ==============================
0129
0130 dfltuid attempt to mount as a particular uid
0131
0132 dfltgid attempt to mount with a particular gid
0133
0134 afid security channel - used by Plan 9 authentication protocols
0135
0136 nodevmap do not map special files - represent them as normal files.
0137 This can be used to share devices/named pipes/sockets between
0138 hosts. This functionality will be expanded in later versions.
0139
0140 access there are four access modes.
0141 user
0142 if a user tries to access a file on v9fs
0143 filesystem for the first time, v9fs sends an
0144 attach command (Tattach) for that user.
0145 This is the default mode.
0146 <uid>
0147 allows only user with uid=<uid> to access
0148 the files on the mounted filesystem
0149 any
0150 v9fs does single attach and performs all
0151 operations as one user
0152 clien
0153 ACL based access check on the 9p client
0154 side for access validation
0155
0156 cachetag cache tag to use the specified persistent cache.
0157 cache tags for existing cache sessions can be listed at
0158 /sys/fs/9p/caches. (applies only to cache=fscache)
0159 ============= ===============================================================
0160
0161 Behavior
0162 ========
0163
0164 This section aims at describing 9p 'quirks' that can be different
0165 from a local filesystem behaviors.
0166
0167 - Setting O_NONBLOCK on a file will make client reads return as early
0168 as the server returns some data instead of trying to fill the read
0169 buffer with the requested amount of bytes or end of file is reached.
0170
0171 Resources
0172 =========
0173
0174 Protocol specifications are maintained on github:
0175 http://ericvh.github.com/9p-rfc/
0176
0177 9p client and server implementations are listed on
0178 http://9p.cat-v.org/implementations
0179
0180 A 9p2000.L server is being developed by LLNL and can be found
0181 at http://code.google.com/p/diod/
0182
0183 There are user and developer mailing lists available through the v9fs project
0184 on sourceforge (http://sourceforge.net/projects/v9fs).
0185
0186 News and other information is maintained on a Wiki.
0187 (http://sf.net/apps/mediawiki/v9fs/index.php).
0188
0189 Bug reports are best issued via the mailing list.
0190
0191 For more information on the Plan 9 Operating System check out
0192 http://plan9.bell-labs.com/plan9
0193
0194 For information on Plan 9 from User Space (Plan 9 applications and libraries
0195 ported to Linux/BSD/OSX/etc) check out https://9fans.github.io/plan9port/
