1NFS_UTIL(3) nfs_util 2.9 NFS_UTIL(3)
2
6 nfstest.nfs_util - NFS utilities module
7
9 Provides a set of tools for testing NFS including methods for starting
10 a packet trace, stopping the packet trace and then open the packet
11 trace for analysis. It also provides a mechanism to enable NFS/RPC
12 kernel debug and saving the log messages for further analysis.
13 Furthermore, methods for finding specific NFSv4 operations within the
15 packet trace are also included.
16
18 class NFSUtil(nfstest.host.Host)
19 NFSUtil object
20 NFSUtil() -> New NFSUtil object
22 Usage:
24 from nfstest.nfs_util import NFSUtil
25 # Create object for local host
27 x = NFSUtil()
28 # Create client host object
30 clientobj = x.create_host('192.168.0.11')
31 # Use buffered matching on packets
33 x.set_pktlist()
34 # Get the next LOOKUP packets
36 pktcall, pktreply = x.find_nfs_op(OP_LOOKUP)
37 # Get OPEN information for the given file name
39 fh, open_stid, deleg_stid = x.find_open(filename="file1")
40 # Get address and port number from universal address string
42 ipaddr, port = x.get_addr_port(addr)
43 # Get packets and DS list for GETDEVICEINFO
45 pktcall, pktreply, dslist = x.find_getdeviceinfo()
46 # Get packets for EXCHANGE_ID
48 pktcall, pktreply = x.find_exchange_id()
49 # Get the NFS operation object from the given packet
51 getfh = x.getop(x.pktreply, OP_GETFH)
52 # Get the stateid which must be used by I/O operations
54 stateid = x.get_stateid("file1")
55 # Get the client id
57 clientid = x.get_clientid()
58 # Get the session id for the given clientid
60 sessionid = x.get_sessionid(clientid=clientid)
61 # Get the root file handle from PUTROOTFH for the given session id
63 x.get_rootfh(sessionid=sessionid)
64 # Get the file handle for the given path
66 dirfh = x.get_pathfh("/vol1/data")
67 # Display the state id in CRC32 format
69 stidstr = x.stid_str(stateid)
70 # Get the number of bytes available in the given directory
72 freebytes = x.get_freebytes("/mnt/t")
73 Methods defined here:
76 ---------------------
77 __del__(self)
79 Destructor
80 __init__(self, **kwargs)
82 Constructor
83 Initialize object's private data.
85 cleanup(self)
87 Gracefully stop the packet trace and un-reference all client
88 objects
89 create_host(self, host, **kwargs)
91 Create client host object and set defaults.
92 find_exchange_id(self, **kwargs)
94 Find the call and its corresponding reply for the NFSv4 EXCHANGE_ID
95 going to the server specified by the ipaddr and port.
96 ipaddr:
99 Destination IP address [default: self.server_ipaddr]
100 port: Destination port [default: self.port]
102 Store the callback IP/TCP expression in object attribute cb_dst
104 Return a tuple: (pktcall, pktreply).
106 find_getdeviceinfo(self, deviceid=None, usecache=True)
108 Find the call and its corresponding reply for the NFSv4 GETDEVICEINFO
109 going to the server specified by the ipaddr for self.server and port
110 given by self.port.
111 deviceid:
114 Look for an specific deviceid [default: any deviceid]
115 usecache:
117 If GETDEVICEINFO is not found look for it in the cache and if
118 deviceid is None use the one found in self.layout.
119 [default: True]
120 Return a tuple: (pktcall, pktreply, dslist).
122 find_layoutget(self, filehandle, status=0)
124 Find the call and its corresponding reply for the NFSv4 LAYOUTGET
125 of the given file handle going to the server specified by the
126 ipaddr for self.server and port given by self.port.
127 Return a tuple: (layoutget, layoutget_res).
129 Layout information is stored in object attribute "layout".
130 find_layoutrecall(self, status=0)
132 Find NFSv4 CB_LAYOUTRECALL call and return its reply.
133 The reply must also match the given status.
134 find_nfs_op(self, op, **kwargs)
136 Find the call and its corresponding reply for the specified NFSv4
137 operation going to the server specified by the ipaddr and port.
138 The reply must also match the given status. Also the following
139 object attributes are defined: pktcall referencing the packet call
140 while pktreply referencing the packet reply.
141 op: NFS operation to find
144 ipaddr:
146 Destination IP address [default: self.server_ipaddr]
147 A value of None matches any IP address
148 port: Destination port [default: self.port]
150 A value of None matches any destination port
151 proto: Protocol [default: self.proto]
153 match: Match string to include [default: '']
155 status:
157 Match the status of the operation [default: 0]
158 A value of None matches any status.
159 src_ipaddr:
161 Source IP address [default: None]
162 A value of None matches any IP address
163 maxindex:
165 The match fails if packet index hits this limit [default: None]
166 A value of None means there is no limit
167 call_only:
169 Find the call only [default: False]
170 first_call:
172 Return on first call even if reply is not found [default: False]
173 last_call:
175 Return last call even if reply is not found [default: False]
176 nfs_version:
178 NFS version to use in search [default: mounted NFS version]
179 Return a tuple: (pktcall, pktreply).
181 find_open(self, **kwargs)
183 Find the call and its corresponding reply for the NFSv4 OPEN of the
184 given file going to the server specified by the ipaddr and port.
185 The following object attributes are defined: opencall and pktcall
186 both referencing the packet call while openreply and pktreply both
187 referencing the packet reply.
188 In the case for NFSv3, search for LOOKUP or CREATE to get the file
189 handle.
190 filename:
193 Find open call and reply for this file [default: None]
194 claimfh:
196 Find open call and reply for this file handle using CLAIM_FH
197 [default: None]
198 ipaddr:
200 Destination IP address [default: self.server_ipaddr]
201 port: Destination port [default: self.port]
203 proto: Protocol [default: self.proto]
205 deleg_type:
207 Expected delegation type on reply [default: None]
208 deleg_stateid:
210 Delegation stateid expected on call in delegate_cur_info [default: None]
211 fh: Find open call and reply for this file handle when using
213 deleg_stateid or as the directory FH when deleg_stateid
214 is not set [default: None]
215 src_ipaddr:
217 Source IP address [default: any IP address]
218 maxindex:
220 The match fails if packet index hits this limit [default: no limit]
221 anyclaim:
223 Find open for either regular open or using delegate_cur_info [default: False]
224 nfs_version:
226 NFS version to use in search [default: mounted NFS version]
227 Must specify either filename, claimfh or both.
229 Return a tuple: (filehandle, open_stateid, deleg_stateid).
230 get_abs_offset(self, offset, ds_index=None)
232 Get real file offset given by the (read/write) offset on the given
233 data server index, taking into account the type of layout
234 (dense/sparse), the stripe_size, first stripe index and the number
235 of filehandles. The layout information is taken from object
236 attribute layout.
237 get_addr_port(self, addr)
239 Get address and port number from universal address string
240 get_clientid(self, **kwargs)
242 Return the client id for the given IP address and port number.
243 ipaddr:
246 Destination IP address [default: self.server_ipaddr]
247 port: Destination port [default: self.port]
249 get_filehandle(self, ds_index)
251 Return filehandle from the layout list of filehandles.
252 get_freebytes(self, dir=None)
254 Get the number of bytes available in the given directory.
255 It takes into account the effective user running the test.
256 The root user is allowed to use all the available disk space
257 on the device, on the other hand a regular user is allowed a
258 little bit less.
259 get_pathfh(self, path, **kwargs)
261 Return the file handle for the given path by searching the packet
262 trace for every component in the path.
263 The file handle for each component is used to search for the file
264 handle in the next component.
265 path: File system path
268 dirfh: Directory file handle to start with [default: None]
270 ipaddr:
272 Destination IP address [default: self.server_ipaddr]
273 port: Destination port [default: self.port]
275 proto: Protocol [default: self.proto]
277 get_rootfh(self, **kwargs)
279 Return the root file handle from PUTROOTFH
280 sessionid:
283 Search the PUTROOTFH tied to this session id [default: None]
284 ipaddr:
286 Destination IP address [default: self.server_ipaddr]
287 port: Destination port [default: self.port]
289 get_sessionid(self, **kwargs)
291 Return the session id for the given IP address and port number.
292 clientid:
295 Search the CREATE_SESSION tied to this client id [default: None]
296 ipaddr:
298 Destination IP address [default: self.server_ipaddr]
299 port: Destination port [default: self.port]
301 get_stateid(self, filename, **kwargs)
303 Search the packet trace for the file name given to get the OPEN
304 so all related state ids can be searched. A couple of object
305 attributes are defined, one is the correct state id that should
306 be used by I/O operations. The second is a dictionary table
307 which maps the state id to a string identifying if the state
308 id is an open, lock or delegation state id.
309 ipaddr:
312 Destination IP address [default: self.server_ipaddr]
313 port: Destination port [default: self.port]
315 noreset:
317 Do not reset the state id map [default: False]
318 write: Search for a write delegation/lock stateid if True or a read
320 delegation/lock stateid if False. Default is to search for
321 any type [default: None]
322 getop(self, pkt, op)
324 Get the NFS operation object from the given packet
325 match_nfs_version(self, nfs_version, post=True)
327 Return the match string to search for the correct NFS version.
328 nfs_version:
331 NFS version to use in search.
332 post: Add "and" conjunction at the end of matching string if this
334 is true. Add it at the beginning if it is false. If this is
335 set to None just return the matching string.
336 nfs_op(self, nfs4, nfs3)
338 Return the item according to what NFS version is mounted
339 nfs_op_name(self, op)
341 Return the name for the given NFSv4 operation or NFSv3 procedure
342 set_pktlist(self, **kwargs)
344 Set the current packet list for buffered matching in which the
345 match method will only use this list instead of getting the next
346 packet from the packet trace file. The default is to get all
347 packets unless any of the arguments is given.
348 NOTE: all READ reply data and all WRITE request data is discarded
350 to avoid having memory issues.
351 layer: Comma separated list of layers to include [default: 'nfs']
354 ops: List of NFSv4 operations to include in the packet list
356 [default: None]
357 cbs: List of NFSv4 callback operations to include in the packet list
359 [default: None]
360 procs: List of NFSv3 procedures to include in the packet list
362 [default: None]
363 maxindex:
365 Include packets up to but not including the packet indexed
366 by this argument [default: None]
367 A value of None means there is no limit
368 pktdisp:
370 Display all cached packets [default: False]
371 stid_str(self, stateid)
373 Display the state id in CRC32 format
374 verify_close(self, filehandle, stateid, pindex=None)
376 Verify CLOSE is sent to the server. Also make sure there is
377 only one CLOSE call sent. Also the following object attributes
378 are defined: pktcall references the first CLOSE call while
379 pktreply references the first CLOSE reply.
380 filehandle:
383 Find CLOSE for this file handle
384 stateid:
386 Open stateid expected
387 pindex:
389 Packet index where to start the search [default: None]
390 verify_commit(self, ipaddr, port, filehandle, init=False)
392 Verify commits are properly sent to the server specified by the
393 given ipaddr and port.
394 ipaddr:
397 Destination IP address of MDS or DS
398 port: Destination port number of MDS or DS
400 filehandle:
402 Find commits for this file handle
403 init: Initialized test variables [default: False]
405 Return the number of commits sent to the server.
407 verify_create_session(self, ipaddr, port, ds=False, nocreate=False, ds_index=None, exchid_status=0, cs_status=0)
409 Verify initial connection to the metadata server(MDS)/data server(DS).
410 Verify if EXCHANGE_ID, CREATE_SESSION, RECLAIM_COMPLETE,
411 GETATTR asking for FATTR4_LEASE_TIME, and GETATTR asking for
412 FATTR4_FS_LAYOUT_TYPES are all sent or not to the server.
413 ipaddr:
416 Destination IP address of MDS or DS
417 port: Destination port number of MDS or DS
419 ds: True if ipaddr/port defines a DS, otherwise MDS [default: False]
421 nocreate:
423 True if expecting the client NOT to send EXCHANGE_ID,
424 CREATE_SESSION, and RECLAIM_COMPLETE. Otherwise, verify all
425 these operations are sent by the client [default: False]
426 ds_index:
428 DS index used for displaying purposes only [default: None]
429 exchid_status:
431 Expected status for EXCHANGE_ID [default: 0]
432 cs_status:
434 Expected status for CREATE_SESSION [default: 0]
435 Return the sessionid and it is also stored in the object
437 attribute sessionid.
438 verify_io(self, iomode, stateid, ipaddr=None, port=None, proto=None, src_ipaddr=None, filehandle=None, ds_index=None, init=False, maxindex=None, pattern=None)
440 Verify I/O is sent to the server specified by the ipaddr and port.
441 iomode:
444 Verify reads (iomode == 1) or writes (iomode == 2)
445 stateid:
447 Expected stateid to use in all I/O requests
448 ipaddr:
450 Destination IP address of MDS or DS
451 [default: do not match destination]
452 port: Destination port number of MDS or DS
454 [default: do not match destination port]
455 proto: Protocol [default: self.proto]
457 src_ipaddr:
459 Source IP address of request
460 [default: do not match source]
461 filehandle:
463 Find I/O for this file handle. This option is used when
464 verifying I/O sent to the MDS
465 [default: use filehandle given by ds_index]
466 ds_index:
468 Data server index. This option is used when verifying I/O sent
469 to the DS -- filehandle is taken from x.layout for this index
470 [default: None]
471 init: Initialized test variables [default: False]
473 maxindex:
475 The match fails if packet index hits this limit [default: no limit]
476 pattern:
478 Data pattern to compare [default: default data pattern]
479 Return the number of I/O operations sent to the server.
481 verify_layoutcommit(self, filehandle, filesize)
483 Verify layoutcommit is properly sent to the server specified by
484 the ipaddr for self.server and port given by self.port.
485 Verify a GETATTR asking for file size is sent within the same
486 compound as the LAYOUTCOMMIT.
487 Verify GETATTR returns correct size for the file.
488 filehandle:
491 Find layoutcommit for this file handle
492 filesize:
494 Expected size of file
495 verify_layoutget(self, filehandle, iomode, riomode=None, status=0, offset=None, length=None, openfh={})
497 Verify the client sends a LAYOUTGET for the given file handle.
498 filehandle:
501 Find LAYOUTGET for this file handle
502 iomode:
504 Expected I/O mode for LAYOUTGET call
505 riomode:
507 Expected I/O mode for LAYOUTGET reply if specified, else verify
508 reply I/O mode is equal to call I/O mode if iomode == 2.
509 If iomode == 1, the reply I/O mode could be equal to 1 or 2
510 status:
512 Expected status for LAYOUTGET reply [default: 0]
513 offset:
515 Expected layout range for LAYOUTGET reply [default: None]
516 length:
518 Expected layout range for LAYOUTGET reply [default: None]
519 openfh:
521 Open information for file (filehandle, open/delegation/lock stateids,
522 and delegation type) if file has been previously opened [default: {}]
523 If both offset and length are not given, verify LAYOUTGET reply
525 should be a full layout [0, NFS4_UINT64_MAX]. If only one is
526 provided the following defaults are used: offset = 0,
527 length = NFS4_UINT64_MAX.
528 Return True if a layout is found and it is supported.
530 verify_layoutreturn(self, layout_list)
532 Verify layoutreturn is properly sent to the server specified by
533 the ipaddr for self.server and port given by self.port.
534 layout_list:
537 List of layouts
538 verify_pnfs_supported(self, filehandle, server_type, path=None, fstype=False)
540 Verify pNFS is supported in the given server path.
541 Finds the GETATTR asking for FATTR4_SUPPORTED_ATTRS(bit 0 and its
542 reply to verify FATTR4_FS_LAYOUT_TYPES is supported for the path.
543 Then it finds the GETATTR asking for FATTR4_FS_LAYOUT_TYPES(bit 62)
544 to verify LAYOUT4_NFSV4_1_FILES is returned in fs_layout_types.
545 verify_stripe(self, offset, size, ds_index)
547 Verify if read/write is sent to the correct data server according
548 to stripe size, first stripe index and the number of filehandles.
549 The layout information is taken from object attribute layout.
550 offset:
553 Real file offset
554 size: I/O size
556 ds_index:
558 Data server index
559 Return True if stripe is correctly verified, False otherwise.
561 Static methods defined here:
563 ----------------------------
564 bitmap_str(bitmap, count, bmap, blist)
566 Return the string representation of bitmap.
567 bitmap:
570 Bitmap to convert
571 count: Number of occurrences of bitmap
573 bmap: Dictionary mapping the bits to strings
575 blist: List of all possible bit combinations
577 iomode_str(iomode)
579 Return a string representation of iomode.
580 This could be run as an instance or class method.
581
583 baseobj(3), formatstr(3), nfstest.host(3), nfstest.utils(3),
584 packet.nfs.nfs3_const(3), packet.nfs.nfs4(3), packet.nfs.nfs4_const(3),
585 packet.unpack(3)
586
589 No known bugs.
590
592 Jorge Mora (mora@netapp.com)
593NFStest 3.2 21 March 2023 NFS_UTIL(3)