Initial revision
[nfs-utils.git] / utils / nhfsstone / nhfsstone.1
1 .\" @(#)nhfsstone.1 1.13 89/10/05 Copyright (c) 1989, Legato Systems Inc
2 .\" See DISCLAIMER file for restrictions
3 .TH NHFSSTONE 1 "4 October 1989"
4 .SH NAME
5 nhfsstone \- Network File System benchmark program
6 .SH SYNOPSIS
7 .B nhfsstone
8 [
9 .B \-v
10 ] [[
11 .B \-t secs
12 ] | [
13 .B -c calls
14 ]] [
15 .B \-l load
16 ] [
17 .B \-p nprocs
18 ] [
19 .B \-m mixfile
20 ] [
21 .B dir
22 ]...
23 .SH DESCRIPTION
24 .B nhfsstone
25 (pronounced n\-f\-s\-stone, the "h" is silent)
26 is used on a
27 .SM NFS
28 client to generate an artificial load with a particular mix of
29 .SM NFS
30 operations. It reports the average response time of the server in
31 milliseconds per call and the load in calls per second.
32 The program adjusts its calling patterns based on the client's kernel
33 .SM NFS
34 statistics and the elapsed time.
35 Load can be generated over a given time or number of
36 .SM NFS
37 calls.
38 .LP
39 Because it uses the kernel
40 .SM NFS
41 statistics to monitor its progress,
42 .B nhfsstone
43 cannot be used to measure the performance of non\-NFS filesystems.
44 .LP
45 The
46 .B nhfsstone
47 program uses file and directory manipulation in an attempt to generate
48 particular
49 .SM NFS
50 operations in response to particular system calls.
51 To do this it uses several tricks
52 that are based on a knowledge of the implementation of the
53 .SM NFS
54 client side reference port.
55 For example, it uses long file names to circumvent the kernel name lookup
56 cache so that a
57 .BR stat (2)
58 system call generates an
59 .SM NFS
60 lookup operation.
61 .LP
62 The mix of
63 .SM NFS
64 operations can be set with a mix file, which is the output of the
65 .BR nfsstat (8C)
66 command (see the "\-m" option below).
67 The percentages taken from
68 the mix file are calculated based on the number of
69 .SM NFS
70 calls, not on the percentages printed by nfsstat. Operations with
71 0% in the mix will never get called by
72 .BR nhfsstone .
73 In a real server load mix, even though the percentage of call for
74 a particular
75 .SM NFS
76 operation may be zero, the number of calls is often nonzero.
77 .B Nhfsstone
78 makes the assumption that the number of calls to these 0 percent
79 operations will have an insignificant effect on server response.
80 .LP
81 Normally
82 .B nhfsstone
83 should be given a list of two or more test directories to use
84 (default is to use the current directory).
85 The test directories used should be located on different disks and
86 partitions on the server to realistically simulate typical server loads.
87 Each
88 .B nhfsstone
89 process looks for a directory
90 .B <dir>/testdir<n>
91 (where <n> is a number from 0 to
92 .B nprocs
93 \- 1).
94 If a process directory name already exists,
95 it is checked for the correct set of test files.
96 Otherwise the directory is created and populated.
97 .SH OPTIONS
98 .TP 12
99 .B \-v
100 Verbose output.
101 .TP
102 .B \-t secs
103 Sets
104 .B calls
105 based on the given running time (in seconds) and the load.
106 .TP
107 .B \-c calls
108 Total number of
109 .SM NFS
110 calls to generate (default is 5000).
111 .TP
112 .B \-l load
113 Load to generate in
114 .SM NFS
115 calls per second (default is 30).
116 .TP
117 .B \-p nprocs
118 Number of load generating sub\-processes to fork (default is 7).
119 This can be used to maximize the amount of load a single machine can generate.
120 On a small client machine (slow CPU or small amount of memory)
121 fewer processes might be used to avoid swapping.
122 .TP
123 .B \-m mixfile
124 Mix of
125 .SM NFS
126 operations to generate.
127 The format of
128 .B mixfile
129 is the same as the output of the
130 .BR nfsstat (8C)
131 program.
132 A mix file can be created on a server by typing "nfsstat \-s > mixfile".
133 The default mix of operations is: null 0%, getattr 13%, setattr 1%,
134 root 0%, lookup 34%, readlink 8%, read 22%, wrcache 0%, write 15%, create 2%,
135 remove 1%, rename 0%, link 0%, symlink 0%, mkdir 0%, rmdir 0%, readdir 3%,
136 fsstat 1%.
137 .SH USING NHFSSTONE
138 As with all benchmarks,
139 .B nhfsstone
140 can only provide numbers that are useful if experiments that use it are
141 set up carefully.
142 Since it is measuring servers, it should be run on a client
143 that will not limit the generation of
144 .SM NFS
145 requests.
146 This means it should have a fast CPU,
147 a good ethernet interface and the machine
148 should not be used for anything else during testing.
149 A Sun\-3/50 can generate about 60
150 .SM NFS
151 calls per second before it runs out of CPU.
152 .LP
153 .B Nhfsstone
154 assumes that all
155 .SM NFS
156 calls generated on the client are going to a single server, and that
157 all of the
158 .SM NFS
159 load on that server is due to this client.
160 To make this assumption hold,
161 both the client and server should be as quiescent as possible during tests.
162 .LP
163 If the network is heavily utilized the delays due to collisions
164 may hide any changes in server performance.
165 High error rates on either the client or server can also
166 cause delays due to retransmissions of lost or damaged packets.
167 .BR netstat (8C)
168 .B \-i
169 can be used to measure the error and collision rates on the client and server.
170 .LP
171 To best simulate the effects of
172 .SM NFS
173 clients on the server, the test
174 directories should be set up so that they are on at least two of the
175 disk partitions that the server exports and the partitions should be
176 as far apart as possible. The
177 .BR dkinfo (8)
178 command can be used to find the physical geometry of disk on BSD based systems.
179 .SM NFS
180 operations tend to randomize
181 access the whole disk so putting all of the
182 .B nhfsstone
183 test directories on a single partition or on
184 two partitions that are close together will not show realistic results.
185 .LP
186 On all tests it is a good idea to run the tests repeatedly and compare results.
187 The number of calls can be increased
188 (with the
189 .B \-c
190 option) until the variance in milliseconds per call is acceptably small.
191 If increasing the number of calls does not help there may be something
192 wrong with the experimental setup.
193 One common problem is too much memory on the client
194 test machine. With too much memory,
195 .B nhfsstone
196 is not able to defeat the client caches and the
197 .SM NFS
198 operations do not end up going to the server at all. If you suspect that
199 there is a caching problem you can use the
200 .B -p
201 option to increase the number of processes.
202 .LP
203 The numbers generated by
204 .B nhfsstone
205 are most useful for comparison if the test setup on the client machine
206 is the same between different server configurations. 
207 Changing
208 .B nhfsstone
209 parameters between runs will produce numbers that can not be
210 meaningfully compared.
211 For example, changing the number of generator processes
212 may affect the measured response
213 time due to context switching or other delays on the client machine, while
214 changing the mix of
215 .SM NFS
216 operations will change the whole nature of the experiment.
217 Other changes to the client configuration may also effect the comparability
218 of results.
219 While
220 .B nhfsstone
221 tries to compensate for differences in client configurations
222 by sampling the actual
223 .SM NFS
224 statistics and adjusting both the load and mix of operations, some changes
225 are not reflected in either the load or the mix. For example, installing
226 a faster CPU or mounting different
227 .SM NFS
228 filesystems may effect the response time without changing either the
229 load or the mix.
230 .LP
231 To do a comparison of different server configurations, first set up the
232 client test directories and do
233 .B nhfsstone
234 runs at different loads to be sure that the variability is
235 reasonably low. Second, run
236 .B nhfsstone
237 at different loads of interest and
238 save the results. Third, change the server configuration (for example,
239 add more memory, replace a disk controller, etc.). Finally, run the same
240 .B nhfsstone
241 loads again and compare the results.
242 .SH SEE ALSO
243 .LP
244 The
245 .B nhfsstone.c
246 source file has comments that describe in detail the operation of
247 of the program.
248 .SH ERROR MESSAGES
249 .TP
250 .B "illegal calls value"
251 The 
252 .B calls
253 argument following the
254 .B \-c
255 flag on the command line is not a positive number.
256 .TP
257 .B "illegal load value"
258 The
259 .B load
260 argument following the
261 .B \-l
262 flag on the command line is not a positive number.
263 .TP
264 .B "illegal time value"
265 The
266 .B time
267 argument following the
268 .B \-t
269 flag on the command line is not a positive number.
270 .TP
271 .B "bad mix file"
272 The
273 .B mixfile
274 file argument following the
275 .B \-m
276 flag on the command line could not be accessed.
277 .TP
278 .B "can't find current directory"
279 The parent process couldn't find the pathname of the current directory.
280 This usually indicates a permission problem.
281 .TP
282 .B "can't fork"
283 The parent couldn't fork the child processes. This usually results from
284 lack of resources, such as memory or swap space.
285 .TP
286 .PD 0
287 .B "can't open log file"
288 .TP
289 .B "can't stat log"
290 .TP
291 .B "can't truncate log"
292 .TP
293 .B "can't write sync file"
294 .TP
295 .B "can't write log"
296 .TP
297 .B "can't read log"
298 .PD
299 A problem occurred during the creation, truncation, reading or writing of the
300 synchronization log file. The parent process creates the
301 log file in /tmp and uses it to synchronize and communicate with its children.
302 .TP
303 .PD 0
304 .B "can't open test directory"
305 .TP
306 .B "can't create test directory"
307 .TP
308 .B "can't cd to test directory"
309 .TP
310 .B "wrong permissions on test dir"
311 .TP
312 .B "can't stat testfile"
313 .TP
314 .B "wrong permissions on testfile"
315 .TP
316 .B "can't create rename file"
317 .TP
318 .B "can't create subdir"
319 .PD
320 A child process had problems creating or checking the contents of its
321 test directory. This is usually due to a permission problem (for example
322 the test directory was created by a different user) or a full filesystem.
323 .TP
324 .PD 0
325 .B "bad mix format: unexpected EOF after 'nfs:'"
326 .TP
327 .B "bad mix format: can't find 'calls' value"
328 .TP
329 .B "bad mix format: unexpected EOF after 'calls'"
330 .TP
331 .B "bad mix format: can't find %d op values"
332 .TP
333 .B "bad mix format: unexpected EOF"
334 .PD
335 A problem occurred while parsing the
336 .B mix
337 file. The expected format of the file is the same as the output of
338 the
339 .BR nfsstat (8C)
340 command when run with the "\-s" option.
341 .TP
342 .B "op failed: "
343 One of the internal pseudo\-NFS operations failed. The name of the operation,
344 e.g. read, write, lookup, will be printed along with an indication of the
345 nature of the failure.
346 .TP
347 .B "select failed"
348 The select system call returned an unexpected error.
349 .SH BUGS
350 .LP
351 Running
352 .B nhfsstone
353 on a non\-NFS filesystem can cause the program to run forever because it
354 uses the kernel NFS statistics to determine when enough calls have been made.
355 .LP
356 .B Nhfsstone
357 uses many file descriptors. The kernel on the client may
358 have to be reconfigured to increase the number of available file table entries.
359 .LP
360 Shell scripts that used
361 .B nhfsstone
362 will have to catch and ignore SIGUSR1 (see
363 .BR signal (3)).
364 This signal is
365 used to synchronize the test processes. If the signal is not caught
366 the shell that is running the script will be killed.
367 .SH FILES
368 .PD 0
369 .TP 20
370 .B /vmunix
371 system namelist
372 .TP
373 .B /dev/kmem
374 kernel virtual memory
375 .TP
376 .B ./testdir*
377 per process test directory
378 .TP
379 .B /tmp/nhfsstone%d
380 process synchronization log file
381 .PD