9p.rst 6.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195
  1. .. SPDX-License-Identifier: GPL-2.0
  2. =======================================
  3. v9fs: Plan 9 Resource Sharing for Linux
  4. =======================================
  5. About
  6. =====
  7. v9fs is a Unix implementation of the Plan 9 9p remote filesystem protocol.
  8. This software was originally developed by Ron Minnich <rminnich@sandia.gov>
  9. and Maya Gokhale. Additional development by Greg Watson
  10. <gwatson@lanl.gov> and most recently Eric Van Hensbergen
  11. <ericvh@gmail.com>, Latchesar Ionkov <lucho@ionkov.net> and Russ Cox
  12. <rsc@swtch.com>.
  13. The best detailed explanation of the Linux implementation and applications of
  14. the 9p client is available in the form of a USENIX paper:
  15. https://www.usenix.org/events/usenix05/tech/freenix/hensbergen.html
  16. Other applications are described in the following papers:
  17. * XCPU & Clustering
  18. http://xcpu.org/papers/xcpu-talk.pdf
  19. * KVMFS: control file system for KVM
  20. http://xcpu.org/papers/kvmfs.pdf
  21. * CellFS: A New Programming Model for the Cell BE
  22. http://xcpu.org/papers/cellfs-talk.pdf
  23. * PROSE I/O: Using 9p to enable Application Partitions
  24. http://plan9.escet.urjc.es/iwp9/cready/PROSE_iwp9_2006.pdf
  25. * VirtFS: A Virtualization Aware File System pass-through
  26. http://goo.gl/3WPDg
  27. Usage
  28. =====
  29. For remote file server::
  30. mount -t 9p 10.10.1.2 /mnt/9
  31. For Plan 9 From User Space applications (http://swtch.com/plan9)::
  32. mount -t 9p `namespace`/acme /mnt/9 -o trans=unix,uname=$USER
  33. For server running on QEMU host with virtio transport::
  34. mount -t 9p -o trans=virtio <mount_tag> /mnt/9
  35. where mount_tag is the tag associated by the server to each of the exported
  36. mount points. Each 9P export is seen by the client as a virtio device with an
  37. associated "mount_tag" property. Available mount tags can be
  38. seen by reading /sys/bus/virtio/drivers/9pnet_virtio/virtio<n>/mount_tag files.
  39. Options
  40. =======
  41. ============= ===============================================================
  42. trans=name select an alternative transport. Valid options are
  43. currently:
  44. ======== ============================================
  45. unix specifying a named pipe mount point
  46. tcp specifying a normal TCP/IP connection
  47. fd used passed file descriptors for connection
  48. (see rfdno and wfdno)
  49. virtio connect to the next virtio channel available
  50. (from QEMU with trans_virtio module)
  51. rdma connect to a specified RDMA channel
  52. ======== ============================================
  53. uname=name user name to attempt mount as on the remote server. The
  54. server may override or ignore this value. Certain user
  55. names may require authentication.
  56. aname=name aname specifies the file tree to access when the server is
  57. offering several exported file systems.
  58. cache=mode specifies a caching policy. By default, no caches are used.
  59. none
  60. default no cache policy, metadata and data
  61. alike are synchronous.
  62. loose
  63. no attempts are made at consistency,
  64. intended for exclusive, read-only mounts
  65. fscache
  66. use FS-Cache for a persistent, read-only
  67. cache backend.
  68. mmap
  69. minimal cache that is only used for read-write
  70. mmap. Northing else is cached, like cache=none
  71. debug=n specifies debug level. The debug level is a bitmask.
  72. ===== ================================
  73. 0x01 display verbose error messages
  74. 0x02 developer debug (DEBUG_CURRENT)
  75. 0x04 display 9p trace
  76. 0x08 display VFS trace
  77. 0x10 display Marshalling debug
  78. 0x20 display RPC debug
  79. 0x40 display transport debug
  80. 0x80 display allocation debug
  81. 0x100 display protocol message debug
  82. 0x200 display Fid debug
  83. 0x400 display packet debug
  84. 0x800 display fscache tracing debug
  85. ===== ================================
  86. rfdno=n the file descriptor for reading with trans=fd
  87. wfdno=n the file descriptor for writing with trans=fd
  88. msize=n the number of bytes to use for 9p packet payload
  89. port=n port to connect to on the remote server
  90. noextend force legacy mode (no 9p2000.u or 9p2000.L semantics)
  91. version=name Select 9P protocol version. Valid options are:
  92. ======== ==============================
  93. 9p2000 Legacy mode (same as noextend)
  94. 9p2000.u Use 9P2000.u protocol
  95. 9p2000.L Use 9P2000.L protocol
  96. ======== ==============================
  97. dfltuid attempt to mount as a particular uid
  98. dfltgid attempt to mount with a particular gid
  99. afid security channel - used by Plan 9 authentication protocols
  100. nodevmap do not map special files - represent them as normal files.
  101. This can be used to share devices/named pipes/sockets between
  102. hosts. This functionality will be expanded in later versions.
  103. access there are four access modes.
  104. user
  105. if a user tries to access a file on v9fs
  106. filesystem for the first time, v9fs sends an
  107. attach command (Tattach) for that user.
  108. This is the default mode.
  109. <uid>
  110. allows only user with uid=<uid> to access
  111. the files on the mounted filesystem
  112. any
  113. v9fs does single attach and performs all
  114. operations as one user
  115. clien
  116. ACL based access check on the 9p client
  117. side for access validation
  118. cachetag cache tag to use the specified persistent cache.
  119. cache tags for existing cache sessions can be listed at
  120. /sys/fs/9p/caches. (applies only to cache=fscache)
  121. ============= ===============================================================
  122. Behavior
  123. ========
  124. This section aims at describing 9p 'quirks' that can be different
  125. from a local filesystem behaviors.
  126. - Setting O_NONBLOCK on a file will make client reads return as early
  127. as the server returns some data instead of trying to fill the read
  128. buffer with the requested amount of bytes or end of file is reached.
  129. Resources
  130. =========
  131. Protocol specifications are maintained on github:
  132. http://ericvh.github.com/9p-rfc/
  133. 9p client and server implementations are listed on
  134. http://9p.cat-v.org/implementations
  135. A 9p2000.L server is being developed by LLNL and can be found
  136. at http://code.google.com/p/diod/
  137. There are user and developer mailing lists available through the v9fs project
  138. on sourceforge (http://sourceforge.net/projects/v9fs).
  139. News and other information is maintained on a Wiki.
  140. (http://sf.net/apps/mediawiki/v9fs/index.php).
  141. Bug reports are best issued via the mailing list.
  142. For more information on the Plan 9 Operating System check out
  143. http://plan9.bell-labs.com/plan9
  144. For information on Plan 9 from User Space (Plan 9 applications and libraries
  145. ported to Linux/BSD/OSX/etc) check out https://9fans.github.io/plan9port/