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