
 Welcome to nfsbench

	Nfsbench is an NFS benchmarking, stress tesing and debugging
	tool. I wrote it mostly to get a benchmark utility that does
	not rely on certain kernel features as nhfsstone does, but it
	has already served me well in finding and locating NFS server
	bugs.

 Copying conditions

	nfsbench is Copyright (C) Olaf Kirch, and may be distributed,
	modified and used under the terms of the GNU General Public
	License, version 2 or later (as you please).

 Brief Introduction

	nfsbench consists of a general RPC layer that mimicks several
	biod daemons. Of course, these aren't real daemons.  The idea is
	to have a gauge of how many concurrent requests will be sent out,
	since each `biod' processes at most one request at a time.

	On top of that sit several RPC protocols, namely PORTMAP, MOUNT,
	and NFS (for now; I would also love to have NLM to be able to
	test lockd). Together, they form something that very closely
	resembles a file system, in that you can mount a directory from
	a remote machine, and perform file system operations on it.
	These individual operations are not yet accessible to the user
	yet, but it shouldn't be too hard to add a decent tcl interface.

	Finally, there are a set of tests and benchmarks, written in C, 
	which use the FS layer. Currently, there are:

	 nfsping	Send a storm of NULL calls to the server to
			gauge network capacity and interface latency.
	 nfswrite	Create a file and write huge amounts of
			data to it.
	 nfsread	Read back data from this file.
	 nfspebbles	A benchmark similar to nhfsstone, which creates
			a bunch of directories and files, and runs a 
			mix of operations on them. Apart from the usual
			RPC stats also printed for all other benchmarks,
			it prints out stuff like the average number of
			operations per second.
	 find		Recursively search a directory hierarchy, and
			optionally delete all files and directories.


 How to use nfsbench

	nfsbench always tries to mount a directory from the NFS server
	before anything else. By default, it will try to mount
	localhost:/tmp/nfsbench, but that can be changed via command-line
	options. This default is mainly a debugging convenience for me.

	On the server, this directory should be exported to the client
	from which you want to test your nfsd. If you don't run under the
	root uid, or if your OS doesn't automatically reserve privileged
	ports to programs running under uid 0, you will have to export
	the directory without privport checking. See your exports(5)
	manpage for details.

	When starting nfsbench, you can give it a number of options:

	-h, --help
		Print short help summary.
	-s, --server
		Hostname or dotted-quad address of NFS server machine.
		Defaults to localhost.
	-p, --port
		Port number on which nfsd runs.
		Defaults to 2049.
	-d, --root
		Name of the directory to be mounted.
		Defaults to /tmp/nfsbench.
	-b, --biods
		The number of biod `processes' as explained above.
		Default is 1.
	-S, --sockets
		The number of sockets used. By default, all biods share
		one socket. On some systems, throughput may improve
		if you use more than. Specifying more sockets than biods
		doesn't make much sense.
	-U, --udp
		Use RPC over UDP. This is the default.
	-T, --tcp
		Use RPC over TCP. Not yet supported.
	-r, --rsize
		The maximum chunk size which will be used for reading files.
		Defaults to 4096.
	-w, --wsize
		The maximum chunk size for writing files.
		Defaults to 4096.

	Following these options, you can specify the name of a benchmark
	to run. Each of these benchmarks take an individual set of options
	described in the following paragraphs.

	The default option understood by all scripts is --help, which
	prints out a short summary of options for that script.

 Running nfsping

	Options:

	-b, --payload
		nfsping will send out calls to the server's NULL procedure
		with some data attached. By default, this payload will
		be 1024 bytes.
	-n, --packets
		This option determines the number of calls made.
		This defaults to 1024.

 Running nfswrite and nfsread

	nfswrite will write data to a file in chunks of wsize bytes;
	nfsread will read data from a file in chunks of rsize bytes.
	You can either specify the number of packets sent, or the
	total number of bytes. If neither is specified, 1024 packets
	are used.

	-f, --file
		Name of file to be written. This defaults to xxx.
	-p, --packets
		Number of packets.
	-n, --bytes
		Total amount of data.
	-o, --offset
		File offset at which to start writing data. Default to 0.


 Running nfspebbles

	nfspebbles first creates a hierarchy of directories and files,
	and then starts to generate random operations on them.

	nfsbench attempts to distribute the number of times each NFS
	operations is performed so that the percentages of a predefined
	mix are met.  You can currently choose from following operations
	mixes:

	legato	The Legato mix used in nhfsstone.
	sundev	The mix used in the Sun Benchmark paper[4].
	debug	A debugging mix that gives all operations equal
		weight. Useful for testing your nfsd under stress
		conditions.

	There is currently no mechnism to specify a user-defined mix.

	The number of files and directories created depends on the mix.
	By default, nfsbench creates 256 of each, but if the percentage
	of rmdir or remove operations exceeds that of mkdir or create
	operations, it will be increased accordingly.


	Options:

	-m, --mix
		Name of mix to use. Defaults to legato.
	-n, --calls
		Total number of calls.
	-f, --size
		The initial size for the files created. The default is
		four times the maximum of rsize and wsize.


Questions

	If you have questions about nfsbench, you can contact me, Olaf,
	at okir@monad.swb.de. You must be a bit patient with me, however,
	because I do not always find the time to answer all my mail
	instantly.


References

 [1]	The Sun Network Filesystem: Design, Implementation and
	Experience; Russel Sandberg
 [2]	NFS Tracing by Passive Network Monitoring; Matt Blaze
 [3]	SPARCserver 490 NFS Performance; Varun Mehta and Rajiv Khemani;
	Sun Server Performance Group; 1991
 [4]	SPARCserver 490 NFS File Server Performance Brief; unknown;
	Sun Micro; 1991
