Scroll to navigation

NFS_UTIL(3) nfs_util 2.9 NFS_UTIL(3)

NAME

nfstest.nfs_util - NFS utilities module

DESCRIPTION

Provides a set of tools for testing NFS including methods for starting a packet trace, stopping the packet trace and then open the packet trace for analysis. It also provides a mechanism to enable NFS/RPC kernel debug and saving the log messages for further analysis.

Furthermore, methods for finding specific NFSv4 operations within the packet trace are also included.

CLASSES

class NFSUtil(nfstest.host.Host)

NFSUtil object
NFSUtil() -> New NFSUtil object
Usage:


    from nfstest.nfs_util import NFSUtil


    # Create object for local host


    x = NFSUtil()


    # Create client host object


    clientobj = x.create_host('192.168.0.11')


    # Use buffered matching on packets


    x.set_pktlist()


    # Get the next LOOKUP packets


    pktcall, pktreply = x.find_nfs_op(OP_LOOKUP)


    # Get OPEN information for the given file name


    fh, open_stid, deleg_stid = x.find_open(filename="file1")


    # Get address and port number from universal address string


    ipaddr, port = x.get_addr_port(addr)


    # Get packets and DS list for GETDEVICEINFO


    pktcall, pktreply, dslist = x.find_getdeviceinfo()


    # Get packets for EXCHANGE_ID


    pktcall, pktreply = x.find_exchange_id()


    # Get the NFS operation object from the given packet


    getfh = x.getop(x.pktreply, OP_GETFH)


    # Get the stateid which must be used by I/O operations


    stateid = x.get_stateid("file1")


    # Get the client id


    clientid = x.get_clientid()


    # Get the session id for the given clientid


    sessionid = x.get_sessionid(clientid=clientid)


    # Get the root file handle from PUTROOTFH for the given session id


    x.get_rootfh(sessionid=sessionid)


    # Get the file handle for the given path


    dirfh = x.get_pathfh("/vol1/data")


    # Display the state id in CRC32 format


    stidstr = x.stid_str(stateid)


    # Get the number of bytes available in the given directory


    freebytes = x.get_freebytes("/mnt/t")

Methods defined here:
---------------------
__del__(self)
Destructor
__init__(self, **kwargs)
Constructor
Initialize object's private data.
cleanup(self)
Gracefully stop the packet trace and un-reference all client
objects
create_host(self, host, **kwargs)
Create client host object and set defaults.
find_exchange_id(self, **kwargs)
Find the call and its corresponding reply for the NFSv4 EXCHANGE_ID
going to the server specified by the ipaddr and port.

Destination IP address [default: self.server_ipaddr]
Destination port [default: self.port]
Store the callback IP/TCP expression in object attribute cb_dst
Return a tuple: (pktcall, pktreply).
find_getdeviceinfo(self, deviceid=None, usecache=True)
Find the call and its corresponding reply for the NFSv4 GETDEVICEINFO
going to the server specified by the ipaddr for self.server and port
given by self.port.

Look for an specific deviceid [default: any deviceid]
If GETDEVICEINFO is not found look for it in the cache and if
deviceid is None use the one found in self.layout.
[default: True]
Return a tuple: (pktcall, pktreply, dslist).
find_layoutget(self, filehandle, status=0)
Find the call and its corresponding reply for the NFSv4 LAYOUTGET
of the given file handle going to the server specified by the
ipaddr for self.server and port given by self.port.
Return a tuple: (layoutget, layoutget_res).
Layout information is stored in object attribute "layout".
find_layoutrecall(self, status=0)
Find NFSv4 CB_LAYOUTRECALL call and return its reply.
The reply must also match the given status.
find_nfs_op(self, op, **kwargs)
Find the call and its corresponding reply for the specified NFSv4
operation going to the server specified by the ipaddr and port.
The reply must also match the given status. Also the following
object attributes are defined: pktcall referencing the packet call
while pktreply referencing the packet reply.

NFS operation to find
Destination IP address [default: self.server_ipaddr]
A value of None matches any IP address
Destination port [default: self.port]
A value of None matches any destination port
Protocol [default: self.proto]
Match string to include [default: '']
Match the status of the operation [default: 0]
A value of None matches any status.
Source IP address [default: None]
A value of None matches any IP address
The match fails if packet index hits this limit [default: None]
A value of None means there is no limit
Find the call only [default: False]
Return on first call even if reply is not found [default: False]
Return last call even if reply is not found [default: False]
NFS version to use in search [default: mounted NFS version]
Return a tuple: (pktcall, pktreply).
find_open(self, **kwargs)
Find the call and its corresponding reply for the NFSv4 OPEN of the
given file going to the server specified by the ipaddr and port.
The following object attributes are defined: opencall and pktcall
both referencing the packet call while openreply and pktreply both
referencing the packet reply.
In the case for NFSv3, search for LOOKUP or CREATE to get the file
handle.

Find open call and reply for this file [default: None]
Find open call and reply for this file handle using CLAIM_FH
[default: None]
Destination IP address [default: self.server_ipaddr]
Destination port [default: self.port]
Protocol [default: self.proto]
Expected delegation type on reply [default: None]
Delegation stateid expected on call in delegate_cur_info [default: None]
Find open call and reply for this file handle when using
deleg_stateid or as the directory FH when deleg_stateid
is not set [default: None]
Source IP address [default: any IP address]
The match fails if packet index hits this limit [default: no limit]
Find open for either regular open or using delegate_cur_info [default: False]
NFS version to use in search [default: mounted NFS version]
Must specify either filename, claimfh or both.
Return a tuple: (filehandle, open_stateid, deleg_stateid).
get_abs_offset(self, offset, ds_index=None)
Get real file offset given by the (read/write) offset on the given
data server index, taking into account the type of layout
(dense/sparse), the stripe_size, first stripe index and the number
of filehandles. The layout information is taken from object
attribute layout.
get_addr_port(self, addr)
Get address and port number from universal address string
get_clientid(self, **kwargs)
Return the client id for the given IP address and port number.

Destination IP address [default: self.server_ipaddr]
Destination port [default: self.port]
get_filehandle(self, ds_index)
Return filehandle from the layout list of filehandles.
get_freebytes(self, dir=None)
Get the number of bytes available in the given directory.
It takes into account the effective user running the test.
The root user is allowed to use all the available disk space
on the device, on the other hand a regular user is allowed a
little bit less.
get_pathfh(self, path, **kwargs)
Return the file handle for the given path by searching the packet
trace for every component in the path.
The file handle for each component is used to search for the file
handle in the next component.

File system path
Directory file handle to start with [default: None]
Destination IP address [default: self.server_ipaddr]
Destination port [default: self.port]
Protocol [default: self.proto]
get_rootfh(self, **kwargs)
Return the root file handle from PUTROOTFH

Search the PUTROOTFH tied to this session id [default: None]
Destination IP address [default: self.server_ipaddr]
Destination port [default: self.port]
get_sessionid(self, **kwargs)
Return the session id for the given IP address and port number.

Search the CREATE_SESSION tied to this client id [default: None]
Destination IP address [default: self.server_ipaddr]
Destination port [default: self.port]
get_stateid(self, filename, **kwargs)
Search the packet trace for the file name given to get the OPEN
so all related state ids can be searched. A couple of object
attributes are defined, one is the correct state id that should
be used by I/O operations. The second is a dictionary table
which maps the state id to a string identifying if the state
id is an open, lock or delegation state id.

Destination IP address [default: self.server_ipaddr]
Destination port [default: self.port]
Do not reset the state id map [default: False]
Search for a write delegation/lock stateid if True or a read
delegation/lock stateid if False. Default is to search for
any type [default: None]
getop(self, pkt, op)
Get the NFS operation object from the given packet
match_nfs_version(self, nfs_version, post=True)
Return the match string to search for the correct NFS version.

NFS version to use in search.
Add "and" conjunction at the end of matching string if this
is true. Add it at the beginning if it is false. If this is
set to None just return the matching string.
nfs_op(self, nfs4, nfs3)
Return the item according to what NFS version is mounted
nfs_op_name(self, op)
Return the name for the given NFSv4 operation or NFSv3 procedure
set_pktlist(self, **kwargs)
Set the current packet list for buffered matching in which the
match method will only use this list instead of getting the next
packet from the packet trace file. The default is to get all
packets unless any of the arguments is given.
NOTE: all READ reply data and all WRITE request data is discarded
to avoid having memory issues.

Comma separated list of layers to include [default: 'nfs']
List of NFSv4 operations to include in the packet list
[default: None]
List of NFSv4 callback operations to include in the packet list
[default: None]
List of NFSv3 procedures to include in the packet list
[default: None]
Include packets up to but not including the packet indexed
by this argument [default: None]
A value of None means there is no limit
Display all cached packets [default: False]
stid_str(self, stateid)
Display the state id in CRC32 format
verify_close(self, filehandle, stateid, pindex=None)
Verify CLOSE is sent to the server. Also make sure there is
only one CLOSE call sent. Also the following object attributes
are defined: pktcall references the first CLOSE call while
pktreply references the first CLOSE reply.

Find CLOSE for this file handle
Open stateid expected
Packet index where to start the search [default: None]
verify_commit(self, ipaddr, port, filehandle, init=False)
Verify commits are properly sent to the server specified by the
given ipaddr and port.

Destination IP address of MDS or DS
Destination port number of MDS or DS
Find commits for this file handle
Initialized test variables [default: False]
Return the number of commits sent to the server.
verify_create_session(self, ipaddr, port, ds=False, nocreate=False, ds_index=None, exchid_status=0, cs_status=0)
Verify initial connection to the metadata server(MDS)/data server(DS).
Verify if EXCHANGE_ID, CREATE_SESSION, RECLAIM_COMPLETE,
GETATTR asking for FATTR4_LEASE_TIME, and GETATTR asking for
FATTR4_FS_LAYOUT_TYPES are all sent or not to the server.

Destination IP address of MDS or DS
Destination port number of MDS or DS
True if ipaddr/port defines a DS, otherwise MDS [default: False]
True if expecting the client NOT to send EXCHANGE_ID,
CREATE_SESSION, and RECLAIM_COMPLETE. Otherwise, verify all
these operations are sent by the client [default: False]
DS index used for displaying purposes only [default: None]
Expected status for EXCHANGE_ID [default: 0]
Expected status for CREATE_SESSION [default: 0]
Return the sessionid and it is also stored in the object
attribute sessionid.
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)
Verify I/O is sent to the server specified by the ipaddr and port.

Verify reads (iomode == 1) or writes (iomode == 2)
Expected stateid to use in all I/O requests
Destination IP address of MDS or DS
[default: do not match destination]
Destination port number of MDS or DS
[default: do not match destination port]
Protocol [default: self.proto]
Source IP address of request
[default: do not match source]
Find I/O for this file handle. This option is used when
verifying I/O sent to the MDS
[default: use filehandle given by ds_index]
Data server index. This option is used when verifying I/O sent
to the DS -- filehandle is taken from x.layout for this index
[default: None]
Initialized test variables [default: False]
The match fails if packet index hits this limit [default: no limit]
Data pattern to compare [default: default data pattern]
Return the number of I/O operations sent to the server.
verify_layoutcommit(self, filehandle, filesize)
Verify layoutcommit is properly sent to the server specified by
the ipaddr for self.server and port given by self.port.
Verify a GETATTR asking for file size is sent within the same
compound as the LAYOUTCOMMIT.
Verify GETATTR returns correct size for the file.

Find layoutcommit for this file handle
Expected size of file
verify_layoutget(self, filehandle, iomode, riomode=None, status=0, offset=None, length=None, openfh={})
Verify the client sends a LAYOUTGET for the given file handle.

Find LAYOUTGET for this file handle
Expected I/O mode for LAYOUTGET call
Expected I/O mode for LAYOUTGET reply if specified, else verify
reply I/O mode is equal to call I/O mode if iomode == 2.
If iomode == 1, the reply I/O mode could be equal to 1 or 2
Expected status for LAYOUTGET reply [default: 0]
Expected layout range for LAYOUTGET reply [default: None]
Expected layout range for LAYOUTGET reply [default: None]
Open information for file (filehandle, open/delegation/lock stateids,
and delegation type) if file has been previously opened [default: {}]
If both offset and length are not given, verify LAYOUTGET reply
should be a full layout [0, NFS4_UINT64_MAX]. If only one is
provided the following defaults are used: offset = 0,
length = NFS4_UINT64_MAX.
Return True if a layout is found and it is supported.
verify_layoutreturn(self, layout_list)
Verify layoutreturn is properly sent to the server specified by
the ipaddr for self.server and port given by self.port.

List of layouts
verify_pnfs_supported(self, filehandle, server_type, path=None, fstype=False)
Verify pNFS is supported in the given server path.
Finds the GETATTR asking for FATTR4_SUPPORTED_ATTRS(bit 0 and its
reply to verify FATTR4_FS_LAYOUT_TYPES is supported for the path.
Then it finds the GETATTR asking for FATTR4_FS_LAYOUT_TYPES(bit 62)
to verify LAYOUT4_NFSV4_1_FILES is returned in fs_layout_types.
verify_stripe(self, offset, size, ds_index)
Verify if read/write is sent to the correct data server according
to stripe size, first stripe index and the number of filehandles.
The layout information is taken from object attribute layout.

Real file offset
I/O size
Data server index
Return True if stripe is correctly verified, False otherwise.
Static methods defined here:
----------------------------
bitmap_str(bitmap, count, bmap, blist)
Return the string representation of bitmap.

Bitmap to convert
Number of occurrences of bitmap
Dictionary mapping the bits to strings
List of all possible bit combinations
iomode_str(iomode)
Return a string representation of iomode.
This could be run as an instance or class method.

SEE ALSO

baseobj(3), formatstr(3), nfstest.host(3), nfstest.utils(3), packet.nfs.nfs3_const(3), packet.nfs.nfs4(3), packet.nfs.nfs4_const(3), packet.unpack(3)

BUGS

No known bugs.

AUTHOR

Jorge Mora (mora@netapp.com)

21 March 2023 NFStest 3.2