1NFSTEST(1)                         NFStest                          NFSTEST(1)
2
3
4

NAME

6       NFStest - NFS Test Suite
7

DESCRIPTION

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
16           - 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
28
29
30   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
36       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
42       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
48       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
53       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

REQUIREMENTS AND LIMITATIONS

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
75       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

TESTS

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
90       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
100       Valid for NFSv4.2 and beyond
101
102   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
107       Valid for any version of NFS
108
109   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
119       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
133       Valid for any version of NFS granting delegations
134
135   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
142       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
145       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
149       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
153       Valid for NFSv4.0 and NFSv4.1 including pNFS
154
155   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
160       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
164   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
170       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
173       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
178       Valid for any version of NFS
179
180   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
188           - 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
197       Only valid using NFSv4.1 with pNFS enabled and file layout type
198
199   nfstest_posix
200       Verify POSIX file system level access over the specified path using
201       positive and negative testing.
202
203       Valid for any version of NFS
204
205   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
211       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
218       Valid for NFSv4.2 and beyond
219
220   nfstest_ssc
221       Verify correct functionality of server side copy
222
223       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
234       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

TOOLS

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
251   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
258   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
267   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
272       Valid for packet traces with NFSv4 and above
273

INSTALLATION

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
279             All manual pages are available
280             $ man nfstest
281
282             Run tests:
283             $ nfstest_pnfs --help
284
285          b. Untar the tarball:
286             Get  the  latest  tarball from http://wiki.linux-nfs.org/wiki/in
287       dex.php/NFStest
288
289             $ tar -zxvf NFStest-2.1.tar.gz
290
291             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
298             Or install to standard python site-packages and executable direc‐
299       tories:
300             $ cd ~/NFStest-2.1
301             $ sudo python setup.py install
302
303             All manual pages are available
304             $ man nfstest
305
306             Run tests:
307             $ nfstest_pnfs --help
308
309          c. Clone the git repository:
310             $ cd ~
311             $ git clone git://git.linux-nfs.org/projects/mora/nfstest.git
312
313             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
320             Or install to standard python site-packages and executable direc‐
321       tories:
322             $ cd ~/nfstest
323             $ sudo python setup.py install
324
325             All manual pages are available
326             $ man nfstest
327
328             Run tests:
329             $ nfstest_pnfs --help
330
331       2. Make sure user running the tests can run commands using 'sudo' with‐
332       out
333          the need for a password.
334
335       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
340       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

EXAMPLES

347       The only required option is --server
348       $ nfstest_pnfs --server 192.168.0.11
349
350       Required options are --server and --client
351       $ nfstest_cache --server 192.168.0.11 --client 192.168.0.20
352
353       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
358       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
363       The only required option is --server
364       $ nfstest_dio --server 192.168.0.11
365
366       The only required option is --server
367       $ nfstest_interop --server 192.168.0.11
368
369       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
373       The only required option is --server
374       $ nfstest_posix --server 192.168.0.11
375
376       The only required option is --server
377       $ nfstest_alloc --server 192.168.0.11
378
379       The only required option is --server
380       $ nfstest_sparse --server 192.168.0.11
381
382       The only required option is --server (run all  intra-server  side  copy
383       tests)
384       $ nfstest_ssc --server 192.168.0.11
385
386       Run all tests (intra & inter)
387       $ nfstest_ssc --server 192.168.0.11 --dst-server 192.168.0.12
388
389       The only required option is --datadir (-d)
390       $ nfstest_io -d /mnt/t/data -v all -n 10 -r 3600
391
392       Display all the NFS packets in the trace file
393       $ nfstest_pkt /tmp/trace.cap
394
395       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
399       Search the packet trace for XID inconsistencies
400       $ nfstest_xid /tmp/trace.cap
401

USEFUL OPTIONS

403       -h, --help
404              All tests have this option to display usage information and  op‐
405              tions available
406
407       --createlog
408              Create log file when specified
409
410       --keeptraces
411              Do not remove any trace files at the end of execution
412
413       -v, --verbose <none|opts|info|debug|all|intbitmask>
414              Verbose level for info/debug messages
415
416              Example:
417                  $ nfstest_posix --server 192.168.0.11 --verbose all
418                  $ nfstest_posix --server 192.168.0.11 --verbose 0x0F
419
420       --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
424              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
429                  Run all the tests except for open and chmod
430                  $ nfstest_posix --server 192.168.0.11 --runtest ^open,chmod
431
432       --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
439              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
453                  $ nfstest_posix --server 192.168.0.11 --tverbose group
454                      PASS:  Verify  POSIX API access() on NFSv4 (58 passed, 0
455              failed)
456
457       --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
465       --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
471       --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
475       --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

SEE ALSO

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
486

BUGS

488       No known bugs.
489

AUTHOR

491       Jorge Mora (mora@netapp.com)
492
493
494
495NFStest 3.2                      21 March 2023                      NFSTEST(1)
Impressum