[deliverable/linux.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://www.xcpu.org/xcpu-talk.pdf
	* KVMFS: control file system for KVM
		http://www.xcpu.org/kvmfs.pdf
	* CellFS: A New ProgrammingModel for the Cell BE
		http://www.xcpu.org/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

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 lguest or KVM with trans_virtio module)

  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

  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

  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 semantics)

  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 three 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

RESOURCES
=========

Our current recommendation is to use Inferno (http://www.vitanuova.com/inferno)
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 CVS 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).

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
	1	v9fs: Plan 9 Resource Sharing for Linux
	2	=======================================
	3
	4	ABOUT
	5	=====
	6
	7	v9fs is a Unix implementation of the Plan 9 9p remote filesystem protocol.
	8
	9	This software was originally developed by Ron Minnich <rminnich@sandia.gov>
	10	and Maya Gokhale. Additional development by Greg Watson
	11	<gwatson@lanl.gov> and most recently Eric Van Hensbergen
	12	<ericvh@gmail.com>, Latchesar Ionkov <lucho@ionkov.net> and Russ Cox
	13	<rsc@swtch.com>.
	14
	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
	21	http://www.xcpu.org/xcpu-talk.pdf
	22	* KVMFS: control file system for KVM
	23	http://www.xcpu.org/kvmfs.pdf
	24	* CellFS: A New ProgrammingModel for the Cell BE
	25	http://www.xcpu.org/cellfs-talk.pdf
	26	* PROSE I/O: Using 9p to enable Application Partitions
	27	http://plan9.escet.urjc.es/iwp9/cready/PROSE_iwp9_2006.pdf
	28
	29	USAGE
	30	=====
	31
	32	For remote file server:
	33
	34	mount -t 9p 10.10.1.2 /mnt/9
	35
	36	For Plan 9 From User Space applications (http://swtch.com/plan9)
	37
	38	mount -t 9p `namespace`/acme /mnt/9 -o trans=unix,uname=$USER
	39
	40	OPTIONS
	41	=======
	42
	43	trans=name select an alternative transport. Valid options are
	44	currently:
	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 lguest or KVM with trans_virtio module)
	51
	52	uname=name user name to attempt mount as on the remote server. The
	53	server may override or ignore this value. Certain user
	54	names may require authentication.
	55
	56	aname=name aname specifies the file tree to access when the server is
	57	offering several exported file systems.
	58
	59	cache=mode specifies a caching policy. By default, no caches are used.
	60	loose = no attempts are made at consistency,
	61	intended for exclusive, read-only mounts
	62
	63	debug=n specifies debug level. The debug level is a bitmask.
	64	0x01 = display verbose error messages
	65	0x02 = developer debug (DEBUG_CURRENT)
	66	0x04 = display 9p trace
	67	0x08 = display VFS trace
	68	0x10 = display Marshalling debug
	69	0x20 = display RPC debug
	70	0x40 = display transport debug
	71	0x80 = display allocation debug
	72
	73	rfdno=n the file descriptor for reading with trans=fd
	74
	75	wfdno=n the file descriptor for writing with trans=fd
	76
	77	maxdata=n the number of bytes to use for 9p packet payload (msize)
	78
	79	port=n port to connect to on the remote server
	80
	81	noextend force legacy mode (no 9p2000.u semantics)
	82
	83	dfltuid attempt to mount as a particular uid
	84
	85	dfltgid attempt to mount with a particular gid
	86
	87	afid security channel - used by Plan 9 authentication protocols
	88
	89	nodevmap do not map special files - represent them as normal files.
	90	This can be used to share devices/named pipes/sockets between
	91	hosts. This functionality will be expanded in later versions.
	92
	93	access there are three access modes.
	94	user = if a user tries to access a file on v9fs
	95	filesystem for the first time, v9fs sends an
	96	attach command (Tattach) for that user.
	97	This is the default mode.
	98	<uid> = allows only user with uid=<uid> to access
	99	the files on the mounted filesystem
	100	any = v9fs does single attach and performs all
	101	operations as one user
	102
	103	RESOURCES
	104	=========
	105
	106	Our current recommendation is to use Inferno (http://www.vitanuova.com/inferno)
	107	as the 9p server. You can start a 9p server under Inferno by issuing the
	108	following command:
	109	; styxlisten -A tcp!!564 export '#U'
	110
	111	The -A specifies an unauthenticated export. The 564 is the port # (you may
	112	have to choose a higher port number if running as a normal user). The '#U*'
	113	specifies exporting the root of the Linux name space. You may specify a
	114	subset of the namespace by extending the path: '#U*'/tmp would just export
	115	/tmp. For more information, see the Inferno manual pages covering styxlisten
	116	and export.
	117
	118	A Linux version of the 9p server is now maintained under the npfs project
	119	on sourceforge (http://sourceforge.net/projects/npfs). The currently
	120	maintained version is the single-threaded version of the server (named spfs)
	121	available from the same CVS repository.
	122
	123	There are user and developer mailing lists available through the v9fs project
	124	on sourceforge (http://sourceforge.net/projects/v9fs).
	125
	126	A stand-alone version of the module (which should build for any 2.6 kernel)
	127	is available via (http://github.com/ericvh/9p-sac/tree/master)
	128
	129	News and other information is maintained on SWiK (http://swik.net/v9fs).
	130
	131	Bug reports may be issued through the kernel.org bugzilla
	132	(http://bugzilla.kernel.org)
	133
	134	For more information on the Plan 9 Operating System check out
	135	http://plan9.bell-labs.com/plan9
	136
	137	For information on Plan 9 from User Space (Plan 9 applications and libraries
	138	ported to Linux/BSD/OSX/etc) check out http://swtch.com/plan9
	139
	140
	141	STATUS
	142	======
	143
	144	The 2.6 kernel support is working on PPC and x86.
	145
	146	PLEASE USE THE KERNEL BUGZILLA TO REPORT PROBLEMS. (http://bugzilla.kernel.org)
	147