[qemu.git] / fsdev / virtfs-proxy-helper.texi

@example
@c man begin SYNOPSIS
usage: virtfs-proxy-helper options
@c man end
@end example

@c man begin DESCRIPTION
@table @description
Pass-through security model in QEMU 9p server needs root privilege to do
few file operations (like chown, chmod to any mode/uid:gid).  There are two
issues in pass-through security model

1) TOCTTOU vulnerability: Following symbolic links in the server could
provide access to files beyond 9p export path.

2) Running QEMU with root privilege could be a security issue.

To overcome above issues, following approach is used: A new filesytem
type 'proxy' is introduced. Proxy FS uses chroot + socket combination
for securing the vulnerability known with following symbolic links.
Intention of adding a new filesystem type is to allow qemu to run
in non-root mode, but doing privileged operations using socket IO.

Proxy helper(a stand alone binary part of qemu) is invoked with
root privileges. Proxy helper chroots into 9p export path and creates
a socket pair or a named socket based on the command line parameter.
QEMU and proxy helper communicate using this socket. QEMU proxy fs
driver sends filesystem request to proxy helper and receives the
response from it.

Proxy helper is designed so that it can drop the root privilege with
retaining capbilities needed for doing filesystem operations only.

@end table
@c man end

@c man begin OPTIONS
The following options are supported:
@table @option
@item -h
@findex -h
Display help and exit
@item -p|--path path
Path to export for proxy filesystem driver
@item -f|--fd socket-id
Use given file descriptor as socket descriptor for communicating with
qemu proxy fs drier. Usually a helper like libvirt will create
socketpair and pass one of the fds as parameter to -f|--fd
@item -s|--socket socket-file
Creates named socket file for communicating with qemu proxy fs driver
@item -u|--uid uid -g|--gid gid
uid:gid combination to give access to named socket file
@item -n|--nodaemon
Run as a normal program. By default program will run in daemon mode
@end table
@c man end

@setfilename virtfs-proxy-helper
@settitle QEMU 9p virtfs proxy filesystem helper

@c man begin AUTHOR
M. Mohan Kumar
@c man end
Commit	Line	Data
a2d8f1be MK	1	@example
	2	@c man begin SYNOPSIS
	3	usage: virtfs-proxy-helper options
	4	@c man end
	5	@end example
	6
	7	@c man begin DESCRIPTION
	8	@table @description
	9	Pass-through security model in QEMU 9p server needs root privilege to do
	10	few file operations (like chown, chmod to any mode/uid:gid). There are two
	11	issues in pass-through security model
	12
	13	1) TOCTTOU vulnerability: Following symbolic links in the server could
	14	provide access to files beyond 9p export path.
	15
	16	2) Running QEMU with root privilege could be a security issue.
	17
	18	To overcome above issues, following approach is used: A new filesytem
	19	type 'proxy' is introduced. Proxy FS uses chroot + socket combination
	20	for securing the vulnerability known with following symbolic links.
	21	Intention of adding a new filesystem type is to allow qemu to run
	22	in non-root mode, but doing privileged operations using socket IO.
	23
	24	Proxy helper(a stand alone binary part of qemu) is invoked with
	25	root privileges. Proxy helper chroots into 9p export path and creates
	26	a socket pair or a named socket based on the command line parameter.
071c9394	27	QEMU and proxy helper communicate using this socket. QEMU proxy fs
a2d8f1be MK	28	driver sends filesystem request to proxy helper and receives the
	29	response from it.
	30
	31	Proxy helper is designed so that it can drop the root privilege with
	32	retaining capbilities needed for doing filesystem operations only.
	33
	34	@end table
	35	@c man end
	36
	37	@c man begin OPTIONS
	38	The following options are supported:
	39	@table @option
	40	@item -h
	41	@findex -h
	42	Display help and exit
	43	@item -p\|--path path
	44	Path to export for proxy filesystem driver
	45	@item -f\|--fd socket-id
	46	Use given file descriptor as socket descriptor for communicating with
	47	qemu proxy fs drier. Usually a helper like libvirt will create
	48	socketpair and pass one of the fds as parameter to -f\|--fd
84a87cc4 MK	49	@item -s\|--socket socket-file
	50	Creates named socket file for communicating with qemu proxy fs driver
	51	@item -u\|--uid uid -g\|--gid gid
	52	uid:gid combination to give access to named socket file
a2d8f1be MK	53	@item -n\|--nodaemon
	54	Run as a normal program. By default program will run in daemon mode
	55	@end table
	56	@c man end
	57
	58	@setfilename virtfs-proxy-helper
	59	@settitle QEMU 9p virtfs proxy filesystem helper
	60
	61	@c man begin AUTHOR
	62	M. Mohan Kumar
	63	@c man end