Debian Codegraph @

README

raw
1 NFS Test Suite
2 ==============
3 Provides a set of tools for testing either the NFS client or the NFS server,
4 included tests focused mainly on testing the client. These tools include the
5 following:
6
7 Test utilities package (nfstest)
8 ================================
9 Provides a set of tools for testing either the NFS client or the NFS server,
10 most of the functionality is focused mainly on testing the client.
11 These tools include the following:
12
13 - Process command line arguments
14 - Provide functionality for PASS/FAIL
15 - Provide test grouping functionality
16 - Provide multiple client support
17 - Logging mechanism
18 - Debug info control
19 - Mount/Unmount control
20 - Create files/directories
21 - Provide mechanism to start a packet trace
22 - Provide mechanism to simulate a network partition
23 - Support for pNFS testing
24
25
26 Packet trace package (packet)
27 =============================
28 Testing NFS has mostly been done using test tools like connectathon test suite,
29 filebench, iozone and others. But mostly using the connectathon test suite.
30 These are good tools for testing, but they are outdated and they also cannot
31 be used for testing pNFS thoroughly.
32
33 For example, you can run the connectathon test suite on pNFS, it runs, it passes
34 all the tests -- but how can we make sure that pNFS worked properly. How can we
35 verify that a layout is granted, but not only that a layout is granted, what
36 type of layout was granted (read, rw). Did the client sent IO to the data
37 servers or to the metadata server.
38
39 The Packet trace module takes a trace file created by tcpdump and unpacks
40 the contents of each packet. You can decode one packet at a time, or do a
41 search for specific packets. The main difference between this modules and
42 other tools used to decode trace files is that you can use this module to
43 completely automate your tests.
44
45 How does it work? It opens the trace file and reads one record at a time
46 keeping track where each record starts. This way, very large trace files
47 can be opened without having to wait for the file to load and avoid loading
48 the whole file into memory.
49
50 Packet layers supported:
51 - ETHERNET II (RFC 894)
52 - IP layer (supports IPv4 and IPv6)
53 - TCP layer
54 - UDP layer
55 - RPC layer
56 - NFS v4.0
57 - NFS v4.1 including pNFS file layouts
58 - NFS v4.2
59 - PORTMAP v2
60 - MOUNT v3
61 - NLM v4
62
63
64 Requirements and limitations
65 ============================
66 In order to run the included tests, the user id in all the client hosts must
67 have access to run commands as root using the 'sudo' command without the need
68 for a password, this includes the host where the test is being executed.
69 This is used to run commands like 'mount' and 'umount'. Furthermore, the
70 user id must be able to ssh to remote hosts without the need for a password
71 if test requires the use of multiple clients.
72
73 Network partition is simulated by the use of 'iptables', please be advised
74 that after every test is run the iptables is flushed and reset so any rules
75 previously setup will be lost. Currently, there is no mechanism to restore
76 the iptables rules to their original state.
77
78
79 Tests
80 =====
81 nfstest_alloc - Space reservation tests
82 =======================================
83 Verify correct functionality of space reservations so applications are
84 able to reserve or unreserve space for a file. The system call fallocate
85 is used to manipulate the allocated disk space for a file, either to
86 preallocate or deallocate it. For filesystems which support the fallocate
87 system call, preallocation is done quickly by allocating blocks and
88 marking them as uninitialized, requiring no I/O to the data blocks.
89 This is much faster than creating a file and filling it with zeros.
90
91 Basic allocate tests verify the disk space is actually preallocated or
92 reserved for the given range by filling up the device after the allocation
93 and make sure data can be written to the allocated range without any
94 problems. Also, any data written outside the allocated range will fail
95 with NFS4ERR_NOSPC when there is no more space left on the device.
96 On the other hand, deallocating space will give the disk space back
97 so it can be used by either the same file on regions not already
98 preallocated or by different files without the risk of getting
99 a no space error.
100
101 Valid for NFSv4.2 and beyond
102
103
104 nfstest_cache - NFS client side caching tests
105 =============================================
106 Verify consistency of attribute caching by varying acregmin, acregmax,
107 acdirmin, acdirmax and actimo. Verify consistency of data caching by varying
108 acregmin, acregmax, acdirmin, acdirmax and actimo.
109
110 Valid for any version of NFS
111
112
113 nfstest_delegation - Delegation tests
114 =====================================
115 Basic delegation tests verify that a correct delegation is granted when
116 opening a file for reading or writing. Also, another OPEN should not be
117 sent for the same file when the client is holding a delegation. Verify
118 that the stateid of all I/O operations should be the delegation stateid.
119 Reads from a different process on the same file should not cause the client
120 to send additional READ packets when the client is holding a read delegation.
121 Furthermore, a LOCK packet should not be sent to the server when the client
122 is holding a delegation.
123
124 Recall delegation tests verify the delegation is recalled when a conflicting
125 operation is sent to the server from a different client. Conflicting operations
126 are reading, writing and changing the permissions on the same file. Note, that
127 reading a file from a different client can only recall a read delegation.
128 Also, verify that a delegation is not recalled when a different client is
129 granted a read delegation. After a delegation is recalled, the client should
130 send an OPEN with CLAIM_DELEGATE_CUR before returning the delegation and the
131 stateid should be the same as the original OPEN stateid. Also, a delegation
132 should not be granted when re-opening the file right before returning
133 the delegation. Verify client flushes all written data before returning
134 the WRITE delegation. The LOCK should be sent as well right before returning
135 a delegation which has been recalled. A delegation should not be granted
136 on the second client who cause the delegation recall on the first client.
137
138 Valid for any version of NFS granting delegations
139
140
141 nfstest_dio - Direct I/O tests
142 ==============================
143 Functional direct I/O tests verify that every READ/WRITE is sent to the server
144 instead of the client caching the requests. Client bypasses read ahead by
145 sending the READ with only the requested bytes. Verify the client correctly
146 handles eof marker when reading the whole file. Verify client ignores delegation
147 while writing a file.
148
149 Direct I/O on pNFS tests verify the client sends the READ/WRITE to the correct
150 DS or the MDS if using a PAGESIZE aligned buffer or not, respectively.
151
152 Direct I/O data correctness tests verify that a file written with buffered I/O
153 is read correctly with direct I/O. Verify that a file written with direct I/O
154 is read correctly with buffered I/O.
155
156 Vectored I/O tests verify coalescence of multiple vectors into one READ/WRITE
157 packet when all vectors are PAGESIZE aligned. Vectors with different alignments
158 are sent on separate packets.
159
160 Valid for NFSv4.0 and NFSv4.1 including pNFS
161
162
163 nfstest_interop - NFS interoperability tests
164 ============================================
165 Basic interoperability tests verify that a file written with different
166 versions of NFS is written correctly. The contents of the file are verified
167 by reading the file back using one of the NFS versions.
168
169 The tests append different data from different versions of NFS one at a
170 time then reads the contents of the file to verify it was written
171 correctly. This is done twice for each test.
172
173
174 nfstest_lock - Locking tests
175 ============================
176 Basic locking tests verify that a lock is granted using various arguments
177 to fcntl. These include blocking and non-blocking locks, read or write locks,
178 where the file is opened either for reading, writing or both. It also checks
179 different ranges including limit conditions.
180
181 Non-overlapping tests verity that locks are granted on both the client under
182 test and a second process or a remote client when locking the same file.
183
184 Overlapping tests verity that a lock is granted on the client under test
185 and a second process or a remote client trying to lock the same file will
186 be denied if a non-blocking lock is issue or will be blocked if a blocking
187 lock is issue on the second process or remote client.
188
189 Valid for any version of NFS
190
191
192 nfstest_pnfs - Basic pNFS functional tests
193 ==========================================
194 Verify basic pNFS functionality for file (both READ and WRITE), including
195 opening a second file within the same mount and having a lock on the file.
196 Also, verify basic pNFS functionality for a file opened for both READ and
197 WRITE while reading the file first and then writing to it or the other way
198 around by writing to the file fist and then reading the file. These tests
199 verify proper functionality of pNFS and NFSv4.1 as well:
200
201 - Verify EXCHANGE_ID is sent to MDS
202 - Verify CREATE_SESSION is sent to MDS
203 - Verify LAYOUTGET is sent to MDS (check layout type, iomode, layout range)
204 - Verify GETDEVICEINFO is sent to MDS
205 - Verify EXCHANGE_ID is sent to the correct DS
206 - Verify CREATE_SESSION is sent to DS
207 - Verify READ/WRITE is sent to DS (check correct stateid, correct offset and size)
208 - Verify no GETATTR is sent to DS
209
210 Only valid using NFSv4.1 with pNFS enabled and file layout type
211
212
213 nfstest_posix - POSIX file system level access tests
214 ====================================================
215 Verify POSIX file system level access over the specified path using
216 positive and negative testing.
217
218 Valid for any version of NFS
219
220
221 nfstest_sparse - Sparse file tests
222 ==================================
223 Verify correct functionality of sparse files. These are files which
224 have unallocated or uninitialized data blocks as holes. The new NFSv4.2
225 operation SEEK is used to search for the next hole or data segment
226 in a file.
227
228 Basic tests verify the SEEK operation returns the correct offset of the
229 next hole or data with respect to the starting offset given to the seek
230 system call. Verify the SEEK operation is sent to the server with the
231 correct stateid as a READ call. All files have a virtual hole at the
232 end of the file so when searching for the next hole, even if the file
233 does not have a hole, it returns the size of the file.
234
235 Valid for NFSv4.2 and beyond
236
237
238 nfstest_ssc - Server Side Copy
239 ==============================
240 Verify correct functionality of server side copy
241
242 Copying a file via NFS the client reads the data from the source file and
243 then writes the same data to the destination file which is located in the
244 same server or it could be located in a different server. Either way the
245 file data is transferred twice, once for reading and the second for writing.
246 Server side copy allows unnecessary network traffic to be eliminated.
247 The intra-server copy allows the client to request the server to perform
248 the copy internally thus avoiding any data being sent through the network
249 at all. In the case for the inter-server copy where the destination server
250 is different from the source server, the client authorizes both servers
251 to interact directly with one another.
252
253 Basic server side copy tests verify the actual file range from the source
254 file(s) are copied correctly to the destination file(s). Most tests deal
255 with a single source and destination file while verifying the data is copied
256 correctly. Also it verifies the data is copied starting from the correct
257 source offset and it is copied to the correct offset on the destination file.
258 Other tests deal with multiple files: copying multiple source files to a
259 single destination file, a single source file to multiple destination files,
260 or N number of source files to M number of destination files.
261
262
263 Tools
264 =====
265 nfstest_io - I/O tool
266 =====================
267 This I/O tool is used to create and manipulate files of different types.
268 The arguments allow running for a specified period of time as well as running
269 multiple processes. Each process modifies a single file at a time and the
270 file name space is different for each process so there are no collisions
271 between two different processes modifying the same file.
272
273 nfstest_pkt - Packet trace decoder
274 ==================================
275 Decode and display all packets in the packet trace file(s) given.
276 The match option gives the ability to search for specific packets within
277 the packet trace file. Other options allow displaying of their corresponding
278 call or reply when only one or the other is matched. Only a range of packets
279 can be displayed if the start and/or end options are used.
280
281 nfstest_file - Find all packets for a specific file
282 ===================================================
283 Display all NFS packets for the specified path. It takes a relative path,
284 where it searches for each of the directory entries given in the path until
285 it gets the file handle for the directory where the file is located. Once the
286 directory file handle is found, a LOOKUP or OPEN/CREATE is searched for the
287 given file name. If the file lookup or creation is found, all file handles
288 and state ids associated with that file are searched and all packets found,
289 including their respective replies are displayed.
290
291
292 nfstest_xid - Verify packets are matched correctly by their XID
293 ===============================================================
294 Search all the packet traces given for XID inconsistencies. Verify all
295 operations in the NFSv4.x COMPOUND reply are the same as the operations
296 given in the call.
297
298 Valid for packet traces with NFSv4 and above
299
300
301 Installation
302 ============
303 1. Install package using one of the following methods:
304 a. Install the rpm as root:
305 # rpm -i NFStest-2.1-1.noarch.rpm
306
307 All manual pages are available
308 $ man nfstest
309
310 Run tests:
311 $ nfstest_pnfs --help
312
313 b. Untar the tarball:
314 Get the latest tarball from http://wiki.linux-nfs.org/wiki/index.php/NFStest
315
316 $ tar -zxvf NFStest-2.1.tar.gz
317
318 The tests can run without installation, just set the python path
319 environment variable:
320 $ cd NFStest-2.1
321 $ export PYTHONPATH=$PWD
322 $ cd test
323 $ ./nfstest_pnfs --help
324
325 Or install to standard python site-packages and executable directories:
326 $ cd ~/NFStest-2.1
327 $ sudo python setup.py install
328
329 All manual pages are available
330 $ man nfstest
331
332 Run tests:
333 $ nfstest_pnfs --help
334
335 c. Clone the git repository:
336 $ cd ~
337 $ git clone git://git.linux-nfs.org/projects/mora/nfstest.git
338
339 The tests can run without installation, just set the python path
340 environment variable:
341 $ cd nfstest
342 $ export PYTHONPATH=$PWD
343 $ cd test
344 $ ./nfstest_pnfs --help
345
346 Or install to standard python site-packages and executable directories:
347 $ cd ~/nfstest
348 $ sudo python setup.py install
349
350 All manual pages are available
351 $ man nfstest
352
353 Run tests:
354 $ nfstest_pnfs --help
355
356 2. Make sure user running the tests can run commands using 'sudo' without
357 the need for a password.
358
359 3. Make sure user running the tests can run commands remotely using 'ssh'
360 without the need for a password. This is only needed for tests which
361 require multiple clients.
362
363 4. Create the mount point specified by the --mtpoint (default: /mnt/t) option
364 on all the clients.
365 $ sudo mkdir /mnt/t
366 $ sudo chmod 777 /mnt/t
367
368
369 Run the tests
370 =============
371 The only required option is --server
372 $ nfstest_pnfs --server 192.168.0.11
373
374 Required options are --server and --client
375 $ nfstest_cache --server 192.168.0.11 --client 192.168.0.20
376
377 Testing with different values of --acmin and --acmax (this takes a long time)
378 $ nfstest_cache --server 192.168.0.11 --client 192.168.0.20 --acmin 10,20 --acmax 20,30,60,80
379
380 The only required option is --server but only the basic delegation tests will
381 be run. In order to run the recall tests the --client option must be used
382 $ nfstest_delegation --server 192.168.0.11 --client 192.168.0.20
383
384 The only required option is --server
385 $ nfstest_dio --server 192.168.0.11
386
387 The only required option is --server
388 $ nfstest_interop --server 192.168.0.11
389
390 The only required option is --server but use the --client option
391 to run the conflicting lock tests
392 $ nfstest_lock --server 192.168.0.11 --client 192.168.0.20
393
394 The only required option is --server
395 $ nfstest_posix --server 192.168.0.11
396
397 The only required option is --server
398 $ nfstest_alloc --server 192.168.0.11
399
400 The only required option is --server
401 $ nfstest_sparse --server 192.168.0.11
402
403 The only required option is --server (run all intra-server side copy tests)
404 $ nfstest_ssc --server 192.168.0.11
405
406 Run all tests (intra & inter)
407 $ nfstest_ssc --server 192.168.0.11 --dst-server 192.168.0.12
408
409 The only required option is --datadir (-d)
410 $ nfstest_io -d /mnt/t/data -v all -n 10 -r 3600
411
412 Display all the NFS packets in the trace file
413 $ nfstest_pkt /tmp/trace.cap
414
415 Display all packets for the file name given
416 The only required option is --path (-p)
417 $ nfstest_file -p f00000001 /tmp/trace.cap
418
419 Search the packet trace for XID inconsistencies
420 $ nfstest_xid /tmp/trace.cap
421
422
423 Useful options
424 ==============
425 -h, --help
426 All tests have this option to display usage information and options available
427
428 --createlog
429 Create log file when specified
430
431 --keeptraces
432 Do not remove any trace files at the end of execution
433
434 -v, --verbose <none|opts|info|debug|all|intbitmask>
435 Verbose level for info/debug messages
436
437 Example:
438 $ nfstest_posix --server 192.168.0.11 --verbose all
439 $ nfstest_posix --server 192.168.0.11 --verbose 0x0F
440
441 --runtest <[^]testname1[,testname2[,...]]>
442 Comma separated list of tests to run, if the first character on the list
443 is '^' then run all the tests except the ones listed.
444
445 Example:
446 Run only the access, chdir, creat and fcntl tests
447 $ nfstest_posix --server 192.168.0.11 --runtest access,chdir,creat,fcntl
448
449 Run all the tests except for open and chmod
450 $ nfstest_posix --server 192.168.0.11 --runtest ^open,chmod
451
452 --tverbose <group|normal|verbose>
453 Verbose level for test messages (default: normal)
454 When tverbose=group, only the test groups are displayed as PASS if all the
455 tests in the group passed, otherwise it will FAIL. In some of the tests
456 tverbose could be 'verbose' for a greater level of verbosity in which a
457 particular test have many sub-tests (>100)
458
459 Example:
460 $ nfstest_posix --server 192.168.0.11
461 *** Verify POSIX API access() on NFSv4
462 PASS: access - file access allowed with mode F_OK
463 PASS: access - file access not allowed with mode F_OK for a non-existent file
464 PASS: access - file access allowed with mode R_OK for file with permissions 0777
465 PASS: access - file access allowed with mode W_OK for file with permissions 0777
466 PASS: access - file access allowed with mode X_OK for file with permissions 0777
467 ...
468
469 $ nfstest_posix --server 192.168.0.11 --tverbose group
470 PASS: Verify POSIX API access() on NFSv4 (58 passed, 0 failed)
471
472 --bugmsgs <filename>
473 File containing test messages to mark as bugs if they failed. When at least
474 one of the tests fails the exit code is set to 1. When this option is
475 specified, all known bugs are not counted as failures so the whole test
476 execution is not failed. If the known bugs actually passed, using this
477 option will fail the test to let the user know that the bug has been fixed.
478
479 --ignore
480 Ignore all bugs given by bugmsgs. If this option is specified all failures
481 given by bugmsgs are ignored. On the other hand, if a test passes which is
482 marked as a bug, using this option the test will not failed as when using
483 the bugmsgs option alone.
484
485 --nfsdebug <flags>
486 Set NFS kernel debug flags and save log messages. Use any of the valid flags
487 given for module 'nfs' on command 'rpcdebug'.
488
489 --rpcdebug <flags>
490 Set RPC kernel debug flags and save log messages. Use any of the valid flags
491 given for module 'rpc' on command 'rpcdebug'.