]>
Commit | Line | Data |
---|---|---|
07d241fd | 1 | .. SPDX-License-Identifier: GPL-2.0 |
93fa58cb | 2 | |
07d241fd MCC |
3 | ======================================= |
4 | v9fs: Plan 9 Resource Sharing for Linux | |
5 | ======================================= | |
6 | ||
7 | About | |
93fa58cb EVH |
8 | ===== |
9 | ||
10 | v9fs is a Unix implementation of the Plan 9 9p remote filesystem protocol. | |
11 | ||
27a2a5ff EVH |
12 | This software was originally developed by Ron Minnich <rminnich@sandia.gov> |
13 | and Maya Gokhale. Additional development by Greg Watson | |
93fa58cb | 14 | <gwatson@lanl.gov> and most recently Eric Van Hensbergen |
ed1f559b EVH |
15 | <ericvh@gmail.com>, Latchesar Ionkov <lucho@ionkov.net> and Russ Cox |
16 | <rsc@swtch.com>. | |
93fa58cb | 17 | |
27a2a5ff EVH |
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: | |
07d241fd | 20 | |
0f540b95 | 21 | https://www.usenix.org/events/usenix05/tech/freenix/hensbergen.html |
27a2a5ff EVH |
22 | |
23 | Other applications are described in the following papers: | |
07d241fd | 24 | |
27a2a5ff | 25 | * XCPU & Clustering |
07d241fd | 26 | http://xcpu.org/papers/xcpu-talk.pdf |
27a2a5ff | 27 | * KVMFS: control file system for KVM |
07d241fd | 28 | http://xcpu.org/papers/kvmfs.pdf |
f4edeeb3 | 29 | * CellFS: A New Programming Model for the Cell BE |
07d241fd | 30 | http://xcpu.org/papers/cellfs-talk.pdf |
27a2a5ff | 31 | * PROSE I/O: Using 9p to enable Application Partitions |
07d241fd | 32 | http://plan9.escet.urjc.es/iwp9/cready/PROSE_iwp9_2006.pdf |
ee294bed | 33 | * VirtFS: A Virtualization Aware File System pass-through |
07d241fd | 34 | http://goo.gl/3WPDg |
27a2a5ff | 35 | |
07d241fd | 36 | Usage |
93fa58cb EVH |
37 | ===== |
38 | ||
07d241fd | 39 | For remote file server:: |
93fa58cb | 40 | |
ed1f559b | 41 | mount -t 9p 10.10.1.2 /mnt/9 |
93fa58cb | 42 | |
07d241fd | 43 | For Plan 9 From User Space applications (http://swtch.com/plan9):: |
93fa58cb | 44 | |
a80d923e | 45 | mount -t 9p `namespace`/acme /mnt/9 -o trans=unix,uname=$USER |
93fa58cb | 46 | |
07d241fd | 47 | For server running on QEMU host with virtio transport:: |
9208d242 SK |
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 | ||
07d241fd | 56 | Options |
93fa58cb EVH |
57 | ======= |
58 | ||
07d241fd | 59 | ============= =============================================================== |
a80d923e | 60 | trans=name select an alternative transport. Valid options are |
93fa58cb | 61 | currently: |
07d241fd MCC |
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 | ======== ============================================ | |
93fa58cb | 72 | |
ed1f559b | 73 | uname=name user name to attempt mount as on the remote server. The |
93fa58cb EVH |
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 | ||
01dd2fbf | 80 | cache=mode specifies a caching policy. By default, no caches are used. |
07d241fd MCC |
81 | |
82 | none | |
83 | default no cache policy, metadata and data | |
b871866e | 84 | alike are synchronous. |
07d241fd MCC |
85 | loose |
86 | no attempts are made at consistency, | |
e03abc0c | 87 | intended for exclusive, read-only mounts |
07d241fd MCC |
88 | fscache |
89 | use FS-Cache for a persistent, read-only | |
f4edeeb3 | 90 | cache backend. |
07d241fd MCC |
91 | mmap |
92 | minimal cache that is only used for read-write | |
b871866e | 93 | mmap. Northing else is cached, like cache=none |
e03abc0c | 94 | |
93fa58cb | 95 | debug=n specifies debug level. The debug level is a bitmask. |
07d241fd MCC |
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 | ===== ================================ | |
93fa58cb | 111 | |
a80d923e | 112 | rfdno=n the file descriptor for reading with trans=fd |
93fa58cb | 113 | |
a80d923e | 114 | wfdno=n the file descriptor for writing with trans=fd |
93fa58cb | 115 | |
14211d02 | 116 | msize=n the number of bytes to use for 9p packet payload |
93fa58cb EVH |
117 | |
118 | port=n port to connect to on the remote server | |
119 | ||
9208d242 SK |
120 | noextend force legacy mode (no 9p2000.u or 9p2000.L semantics) |
121 | ||
122 | version=name Select 9P protocol version. Valid options are: | |
07d241fd MCC |
123 | |
124 | ======== ============================== | |
125 | 9p2000 Legacy mode (same as noextend) | |
126 | 9p2000.u Use 9P2000.u protocol | |
127 | 9p2000.L Use 9P2000.L protocol | |
128 | ======== ============================== | |
93fa58cb | 129 | |
bd32b82d | 130 | dfltuid attempt to mount as a particular uid |
93fa58cb | 131 | |
bd32b82d | 132 | dfltgid attempt to mount with a particular gid |
93fa58cb EVH |
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 | ||
76381a42 | 140 | access there are four access modes. |
07d241fd MCC |
141 | user |
142 | if a user tries to access a file on v9fs | |
ba17674f LI |
143 | filesystem for the first time, v9fs sends an |
144 | attach command (Tattach) for that user. | |
145 | This is the default mode. | |
07d241fd MCC |
146 | <uid> |
147 | allows only user with uid=<uid> to access | |
ba17674f | 148 | the files on the mounted filesystem |
07d241fd MCC |
149 | any |
150 | v9fs does single attach and performs all | |
ba17674f | 151 | operations as one user |
07d241fd MCC |
152 | clien |
153 | ACL based access check on the 9p client | |
76381a42 | 154 | side for access validation |
ba17674f | 155 | |
f4edeeb3 AK |
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) | |
07d241fd | 159 | ============= =============================================================== |
f4edeeb3 | 160 | |
5d30bcac | 161 | Behavior |
c6f14141 DM |
162 | ======== |
163 | ||
164 | This section aims at describing 9p 'quirks' that can be different | |
165 | from 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 | ||
07d241fd | 171 | Resources |
93fa58cb EVH |
172 | ========= |
173 | ||
ee294bed EVH |
174 | Protocol specifications are maintained on github: |
175 | http://ericvh.github.com/9p-rfc/ | |
ff76e1df | 176 | |
ee294bed EVH |
177 | 9p client and server implementations are listed on |
178 | http://9p.cat-v.org/implementations | |
ff76e1df | 179 | |
ee294bed EVH |
180 | A 9p2000.L server is being developed by LLNL and can be found |
181 | at http://code.google.com/p/diod/ | |
e1c92117 EVH |
182 | |
183 | There are user and developer mailing lists available through the v9fs project | |
184 | on sourceforge (http://sourceforge.net/projects/v9fs). | |
185 | ||
ee294bed EVH |
186 | News and other information is maintained on a Wiki. |
187 | (http://sf.net/apps/mediawiki/v9fs/index.php). | |
e1c92117 | 188 | |
b871866e | 189 | Bug reports are best issued via the mailing list. |
93fa58cb EVH |
190 | |
191 | For more information on the Plan 9 Operating System check out | |
192 | http://plan9.bell-labs.com/plan9 | |
193 | ||
194 | For information on Plan 9 from User Space (Plan 9 applications and libraries | |
b529c06f | 195 | ported to Linux/BSD/OSX/etc) check out https://9fans.github.io/plan9port/ |