[net-next-2.6.git] / Documentation / filesystems / 9p.txt

	  	    v9fs: Plan 9 Resource Sharing for Linux
		    =======================================

ABOUT
=====

v9fs is a Unix implementation of the Plan 9 9p remote filesystem protocol.

This software was originally developed by Ron Minnich <rminnich@sandia.gov>
and Maya Gokhale.  Additional development by Greg Watson
<gwatson@lanl.gov> and most recently Eric Van Hensbergen
<ericvh@gmail.com>, Latchesar Ionkov <lucho@ionkov.net> and Russ Cox
<rsc@swtch.com>.

The best detailed explanation of the Linux implementation and applications of
the 9p client is available in the form of a USENIX paper:
   http://www.usenix.org/events/usenix05/tech/freenix/hensbergen.html

Other applications are described in the following papers:
	* XCPU & Clustering
		http://xcpu.org/papers/xcpu-talk.pdf
	* KVMFS: control file system for KVM
		http://xcpu.org/papers/kvmfs.pdf
	* CellFS: A New Programming Model for the Cell BE
		http://xcpu.org/papers/cellfs-talk.pdf
	* PROSE I/O: Using 9p to enable Application Partitions
		http://plan9.escet.urjc.es/iwp9/cready/PROSE_iwp9_2006.pdf

USAGE
=====

For remote file server:

	mount -t 9p 10.10.1.2 /mnt/9

For Plan 9 From User Space applications (http://swtch.com/plan9)

	mount -t 9p `namespace`/acme /mnt/9 -o trans=unix,uname=$USER

For server running on QEMU host with virtio transport:

	mount -t 9p -o trans=virtio <mount_tag> /mnt/9

where mount_tag is the tag associated by the server to each of the exported
mount points. Each 9P export is seen by the client as a virtio device with an
associated "mount_tag" property. Available mount tags can be
seen by reading /sys/bus/virtio/drivers/9pnet_virtio/virtio<n>/mount_tag files.

OPTIONS
=======

  trans=name	select an alternative transport.  Valid options are
  		currently:
			unix 	- specifying a named pipe mount point
			tcp	- specifying a normal TCP/IP connection
			fd   	- used passed file descriptors for connection
                                (see rfdno and wfdno)
			virtio	- connect to the next virtio channel available
				(from QEMU with trans_virtio module)
			rdma	- connect to a specified RDMA channel

  uname=name	user name to attempt mount as on the remote server.  The
  		server may override or ignore this value.  Certain user
		names may require authentication.

  aname=name	aname specifies the file tree to access when the server is
  		offering several exported file systems.

  cache=mode	specifies a caching policy.  By default, no caches are used.
			loose = no attempts are made at consistency,
                                intended for exclusive, read-only mounts
			fscache = use FS-Cache for a persistent, read-only
				cache backend.

  debug=n	specifies debug level.  The debug level is a bitmask.
			0x01  = display verbose error messages
			0x02  = developer debug (DEBUG_CURRENT)
			0x04  = display 9p trace
			0x08  = display VFS trace
			0x10  = display Marshalling debug
			0x20  = display RPC debug
			0x40  = display transport debug
			0x80  = display allocation debug
			0x100 = display protocol message debug
			0x200 = display Fid debug
			0x400 = display packet debug
			0x800 = display fscache tracing debug

  rfdno=n	the file descriptor for reading with trans=fd

  wfdno=n	the file descriptor for writing with trans=fd

  maxdata=n	the number of bytes to use for 9p packet payload (msize)

  port=n	port to connect to on the remote server

  noextend	force legacy mode (no 9p2000.u or 9p2000.L semantics)

  version=name	Select 9P protocol version. Valid options are:
			9p2000          - Legacy mode (same as noextend)
			9p2000.u        - Use 9P2000.u protocol
			9p2000.L        - Use 9P2000.L protocol

  dfltuid	attempt to mount as a particular uid

  dfltgid	attempt to mount with a particular gid

  afid		security channel - used by Plan 9 authentication protocols

  nodevmap	do not map special files - represent them as normal files.
  		This can be used to share devices/named pipes/sockets between
		hosts.  This functionality will be expanded in later versions.

  access	there are four access modes.
			user  = if a user tries to access a file on v9fs
			        filesystem for the first time, v9fs sends an
			        attach command (Tattach) for that user.
				This is the default mode.
			<uid> = allows only user with uid=<uid> to access
				the files on the mounted filesystem
			any   = v9fs does single attach and performs all
				operations as one user
			client = ACL based access check on the 9p client
			         side for access validation

  cachetag	cache tag to use the specified persistent cache.
		cache tags for existing cache sessions can be listed at
		/sys/fs/9p/caches. (applies only to cache=fscache)

RESOURCES
=========

Our current recommendation is to use Inferno (http://www.vitanuova.com/nferno/index.html)
as the 9p server.  You can start a 9p server under Inferno by issuing the
following command:
   ; styxlisten -A tcp!*!564 export '#U*'

The -A specifies an unauthenticated export.  The 564 is the port # (you may
have to choose a higher port number if running as a normal user).  The '#U*'
specifies exporting the root of the Linux name space.  You may specify a
subset of the namespace by extending the path: '#U*'/tmp would just export
/tmp.  For more information, see the Inferno manual pages covering styxlisten
and export.

A Linux version of the 9p server is now maintained under the npfs project
on sourceforge (http://sourceforge.net/projects/npfs).  The currently
maintained version is the single-threaded version of the server (named spfs)
available from the same SVN repository.

There are user and developer mailing lists available through the v9fs project
on sourceforge (http://sourceforge.net/projects/v9fs).

A stand-alone version of the module (which should build for any 2.6 kernel)
is available via (http://github.com/ericvh/9p-sac/tree/master)

News and other information is maintained on SWiK (http://swik.net/v9fs)
and the Wiki (http://sf.net/apps/mediawiki/v9fs/index.php).

Bug reports may be issued through the kernel.org bugzilla 
(http://bugzilla.kernel.org)

For more information on the Plan 9 Operating System check out
http://plan9.bell-labs.com/plan9

For information on Plan 9 from User Space (Plan 9 applications and libraries
ported to Linux/BSD/OSX/etc) check out http://swtch.com/plan9


STATUS
======

The 2.6 kernel support is working on PPC and x86.

PLEASE USE THE KERNEL BUGZILLA TO REPORT PROBLEMS. (http://bugzilla.kernel.org)
Commit	Line	Data
ed1f559b EVH	1	v9fs: Plan 9 Resource Sharing for Linux
ed1f559b EVH	2	=======================================
93fa58cb EVH	3
	4	ABOUT
	5	=====
	6
	7	v9fs is a Unix implementation of the Plan 9 9p remote filesystem protocol.
	8
27a2a5ff EVH	9	This software was originally developed by Ron Minnich <rminnich@sandia.gov>
27a2a5ff EVH	10	and Maya Gokhale. Additional development by Greg Watson
93fa58cb	11	<gwatson@lanl.gov> and most recently Eric Van Hensbergen
ed1f559b EVH	12	<ericvh@gmail.com>, Latchesar Ionkov <lucho@ionkov.net> and Russ Cox
ed1f559b EVH	13	<rsc@swtch.com>.
93fa58cb	14
27a2a5ff EVH	15	The best detailed explanation of the Linux implementation and applications of
	16	the 9p client is available in the form of a USENIX paper:
	17	http://www.usenix.org/events/usenix05/tech/freenix/hensbergen.html
	18
	19	Other applications are described in the following papers:
	20	* XCPU & Clustering
f4edeeb3	21	http://xcpu.org/papers/xcpu-talk.pdf
27a2a5ff	22	* KVMFS: control file system for KVM
f4edeeb3 AK	23	http://xcpu.org/papers/kvmfs.pdf
	24	* CellFS: A New Programming Model for the Cell BE
	25	http://xcpu.org/papers/cellfs-talk.pdf
27a2a5ff EVH	26	* PROSE I/O: Using 9p to enable Application Partitions
	27	http://plan9.escet.urjc.es/iwp9/cready/PROSE_iwp9_2006.pdf
	28
93fa58cb EVH	29	USAGE
	30	=====
	31
	32	For remote file server:
	33
ed1f559b	34	mount -t 9p 10.10.1.2 /mnt/9
93fa58cb EVH	35
	36	For Plan 9 From User Space applications (http://swtch.com/plan9)
	37
a80d923e	38	mount -t 9p `namespace`/acme /mnt/9 -o trans=unix,uname=$USER
93fa58cb	39
9208d242 SK	40	For server running on QEMU host with virtio transport:
	41
	42	mount -t 9p -o trans=virtio <mount_tag> /mnt/9
	43
	44	where mount_tag is the tag associated by the server to each of the exported
	45	mount points. Each 9P export is seen by the client as a virtio device with an
	46	associated "mount_tag" property. Available mount tags can be
	47	seen by reading /sys/bus/virtio/drivers/9pnet_virtio/virtio<n>/mount_tag files.
	48
93fa58cb EVH	49	OPTIONS
	50	=======
	51
a80d923e	52	trans=name select an alternative transport. Valid options are
93fa58cb	53	currently:
b530cc79 EVH	54	unix - specifying a named pipe mount point
	55	tcp - specifying a normal TCP/IP connection
	56	fd - used passed file descriptors for connection
93fa58cb	57	(see rfdno and wfdno)
b530cc79	58	virtio - connect to the next virtio channel available
9208d242	59	(from QEMU with trans_virtio module)
f4edeeb3	60	rdma - connect to a specified RDMA channel
93fa58cb	61
ed1f559b	62	uname=name user name to attempt mount as on the remote server. The
93fa58cb EVH	63	server may override or ignore this value. Certain user
	64	names may require authentication.
	65
	66	aname=name aname specifies the file tree to access when the server is
	67	offering several exported file systems.
	68
01dd2fbf	69	cache=mode specifies a caching policy. By default, no caches are used.
e03abc0c EVH	70	loose = no attempts are made at consistency,
e03abc0c EVH	71	intended for exclusive, read-only mounts
f4edeeb3 AK	72	fscache = use FS-Cache for a persistent, read-only
f4edeeb3 AK	73	cache backend.
e03abc0c	74
93fa58cb	75	debug=n specifies debug level. The debug level is a bitmask.
f4edeeb3 AK	76	0x01 = display verbose error messages
	77	0x02 = developer debug (DEBUG_CURRENT)
	78	0x04 = display 9p trace
	79	0x08 = display VFS trace
	80	0x10 = display Marshalling debug
	81	0x20 = display RPC debug
	82	0x40 = display transport debug
	83	0x80 = display allocation debug
	84	0x100 = display protocol message debug
	85	0x200 = display Fid debug
	86	0x400 = display packet debug
	87	0x800 = display fscache tracing debug
93fa58cb	88
a80d923e	89	rfdno=n the file descriptor for reading with trans=fd
93fa58cb	90
a80d923e	91	wfdno=n the file descriptor for writing with trans=fd
93fa58cb	92
ed1f559b	93	maxdata=n the number of bytes to use for 9p packet payload (msize)
93fa58cb EVH	94
	95	port=n port to connect to on the remote server
	96
9208d242 SK	97	noextend force legacy mode (no 9p2000.u or 9p2000.L semantics)
	98
	99	version=name Select 9P protocol version. Valid options are:
	100	9p2000 - Legacy mode (same as noextend)
	101	9p2000.u - Use 9P2000.u protocol
	102	9p2000.L - Use 9P2000.L protocol
93fa58cb	103
bd32b82d	104	dfltuid attempt to mount as a particular uid
93fa58cb	105
bd32b82d	106	dfltgid attempt to mount with a particular gid
93fa58cb EVH	107
	108	afid security channel - used by Plan 9 authentication protocols
	109
	110	nodevmap do not map special files - represent them as normal files.
	111	This can be used to share devices/named pipes/sockets between
	112	hosts. This functionality will be expanded in later versions.
	113
76381a42	114	access there are four access modes.
ba17674f LI	115	user = if a user tries to access a file on v9fs
	116	filesystem for the first time, v9fs sends an
	117	attach command (Tattach) for that user.
	118	This is the default mode.
	119	<uid> = allows only user with uid=<uid> to access
	120	the files on the mounted filesystem
	121	any = v9fs does single attach and performs all
	122	operations as one user
76381a42 AK	123	client = ACL based access check on the 9p client
76381a42 AK	124	side for access validation
ba17674f	125
f4edeeb3 AK	126	cachetag cache tag to use the specified persistent cache.
	127	cache tags for existing cache sessions can be listed at
	128	/sys/fs/9p/caches. (applies only to cache=fscache)
	129
93fa58cb EVH	130	RESOURCES
	131	=========
	132
0ea6e611	133	Our current recommendation is to use Inferno (http://www.vitanuova.com/nferno/index.html)
ff76e1df EVH	134	as the 9p server. You can start a 9p server under Inferno by issuing the
	135	following command:
	136	; styxlisten -A tcp!!564 export '#U'
	137
	138	The -A specifies an unauthenticated export. The 564 is the port # (you may
	139	have to choose a higher port number if running as a normal user). The '#U*'
	140	specifies exporting the root of the Linux name space. You may specify a
	141	subset of the namespace by extending the path: '#U*'/tmp would just export
	142	/tmp. For more information, see the Inferno manual pages covering styxlisten
	143	and export.
	144
	145	A Linux version of the 9p server is now maintained under the npfs project
27a2a5ff EVH	146	on sourceforge (http://sourceforge.net/projects/npfs). The currently
27a2a5ff EVH	147	maintained version is the single-threaded version of the server (named spfs)
f4edeeb3	148	available from the same SVN repository.
e1c92117 EVH	149
	150	There are user and developer mailing lists available through the v9fs project
	151	on sourceforge (http://sourceforge.net/projects/v9fs).
	152
7815f4be EVH	153	A stand-alone version of the module (which should build for any 2.6 kernel)
	154	is available via (http://github.com/ericvh/9p-sac/tree/master)
	155
f4edeeb3 AK	156	News and other information is maintained on SWiK (http://swik.net/v9fs)
f4edeeb3 AK	157	and the Wiki (http://sf.net/apps/mediawiki/v9fs/index.php).
e1c92117 EVH	158
	159	Bug reports may be issued through the kernel.org bugzilla
	160	(http://bugzilla.kernel.org)
93fa58cb EVH	161
	162	For more information on the Plan 9 Operating System check out
	163	http://plan9.bell-labs.com/plan9
	164
	165	For information on Plan 9 from User Space (Plan 9 applications and libraries
	166	ported to Linux/BSD/OSX/etc) check out http://swtch.com/plan9
	167
	168
	169	STATUS
	170	======
	171
	172	The 2.6 kernel support is working on PPC and x86.
	173
ff76e1df	174	PLEASE USE THE KERNEL BUGZILLA TO REPORT PROBLEMS. (http://bugzilla.kernel.org)
93fa58cb	175