NFS_UTIL(3)

📦 version 3.2, in debian trixie, fedora 43, fedora 44, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 NFS_UTIL(3) 💖

bestie welcome to the manual page for nfs_util, straight out of nfs_util 2.9. it's giving reference material. it's giving "i will read this at 2am while my test is failing." let's go 🫶

✨ NAME ✨

nfstest.nfs_util — the NFS utilities module. iconic. no notes. 💅

🌸 DESCRIPTION 🌸

okay so this module hands you a whole little toolkit for testing NFS, and honestly? it's a lot and it's good.

it gives you methods to start a packet trace, stop the packet trace, and then open the packet trace back up for analysis. it also gives you a mechanism to enable NFS/RPC kernel debug and save the log messages so you can dig into them later. iykyk.

on top of that? it's got methods for finding specific NFSv4 operations inside the packet trace. yeah. it's that girl. 🔥

🎀 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. it's the goodbye method. the farewell era. 🦋

__init__(self, **kwargs)

Constructor.

Initialize the object's private data. very "let me set up my little world first." 💜

cleanup(self)

Gracefully stop the packet trace and un-reference all client objects. tidy bestie behavior. we love a clean exit. ✨

create_host(self, host, **kwargs)

Create a client host object and set defaults. boom, new host, welcome to the party 🎀

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.

  • ipaddr — Destination IP address [default: self.server_ipaddr]
  • port — 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.

  • deviceid — Look for an specific deviceid [default: any deviceid]
  • usecache — 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 the 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.

  • op — NFS operation to find
  • ipaddr — Destination IP address [default: self.server_ipaddr]. A value of None matches any IP address
  • port — Destination port [default: self.port]. A value of None matches any destination port
  • proto — Protocol [default: self.proto]
  • match — Match string to include [default: '']
  • status — Match the status of the operation [default: 0]. A value of None matches any status
  • src_ipaddr — Source IP address [default: None]. A value of None matches any IP address
  • maxindex — The match fails if packet index hits this limit [default: None]. A value of None means there is no limit
  • call_only — Find the call only [default: False]
  • first_call — Return on first call even if reply is not found [default: False]
  • last_call — Return last call even if reply is not found [default: False]
  • nfs_version — 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.

  • filename — Find open call and reply for this file [default: None]
  • claimfh — Find open call and reply for this file handle using CLAIM_FH [default: None]
  • ipaddr — Destination IP address [default: self.server_ipaddr]
  • port — Destination port [default: self.port]
  • proto — Protocol [default: self.proto]
  • deleg_type — Expected delegation type on reply [default: None]
  • deleg_stateid — Delegation stateid expected on call in delegate_cur_info [default: None]
  • fh — 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]
  • src_ipaddr — Source IP address [default: any IP address]
  • maxindex — The match fails if packet index hits this limit [default: no limit]
  • anyclaim — Find open for either regular open or using delegate_cur_info [default: False]
  • nfs_version — NFS version to use in search [default: mounted NFS version]
bestie, you must specify either filename, claimfh, or both. no skipping this one. 🙈

Return a tuple: (filehandle, open_stateid, deleg_stateid).

get_abs_offset(self, offset, ds_index=None)

Get the 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 a universal address string. 💫

get_clientid(self, **kwargs)

Return the client id for the given IP address and port number.

  • ipaddr — Destination IP address [default: self.server_ipaddr]
  • port — Destination port [default: self.port]

get_filehandle(self, ds_index)

Return the 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. one by one, bestie, we get there 🧚

  • path — File system path
  • dirfh — Directory file handle to start with [default: None]
  • ipaddr — Destination IP address [default: self.server_ipaddr]
  • port — Destination port [default: self.port]
  • proto — Protocol [default: self.proto]

get_rootfh(self, **kwargs)

Return the root file handle from PUTROOTFH.

  • sessionid — Search the PUTROOTFH tied to this session id [default: None]
  • ipaddr — Destination IP address [default: self.server_ipaddr]
  • port — Destination port [default: self.port]

get_sessionid(self, **kwargs)

Return the session id for the given IP address and port number.

  • clientid — Search the CREATE_SESSION tied to this client id [default: None]
  • ipaddr — Destination IP address [default: self.server_ipaddr]
  • port — Destination port [default: self.port]

get_stateid(self, filename, **kwargs)

Search the packet trace for the filename 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. 💜

  • ipaddr — Destination IP address [default: self.server_ipaddr]
  • port — Destination port [default: self.port]
  • noreset — Do not reset the state id map [default: False]
  • write — 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 — NFS version to use in search.
  • post — Add "and" conjunction at the end of the 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.

okay and that's part one bestie, we're not done yet — more is coming so don't go anywhere 💖

nfs_op(self, nfs4, nfs3)

hands you back the right item depending on what NFS version is actually mounted 💅

nfs_op_name(self, op)

give it an op and it returns the name for the given NFSv4 operation or NFSv3 procedure. slay.

set_pktlist(self, **kwargs)

Sets the current packet list for buffered matching — and the way this works is that the match method will only use this list instead of getting the next packet from the packet trace file. The default vibe 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. 💀 like, it's for your own good bestie.
  • layer — Comma separated list of layers to include [default: 'nfs']
  • ops — List of NFSv4 operations to include in the packet list [default: None]
  • cbs — List of NFSv4 callback operations to include in the packet list [default: None]
  • procs — List of NFSv3 procedures to include in the packet list [default: None]
  • maxindex — Include packets up to but not including the packet indexed by this argument [default: None]. A value of None means there is no limit 🦋
  • pktdisp — Display all cached packets [default: False]

stid_str(self, stateid)

Displays the state id in CRC32 format. cute and compact, we love.

verify_close(self, filehandle, stateid, pindex=None)

Verifies CLOSE is sent to the server. Also makes sure there's only one CLOSE call sent. Also, the following object attributes get defined: pktcall references the first CLOSE call while pktreply references the first CLOSE reply. two attributes, one iconic duo 🫶

  • filehandle — Find CLOSE for this file handle
  • stateid — Open stateid expected
  • pindex — Packet index where to start the search [default: None]

verify_commit(self, ipaddr, port, filehandle, init=False)

Verifies commits are properly sent to the server specified by the given ipaddr and port. fr fr.

  • ipaddr — Destination IP address of MDS or DS
  • port — Destination port number of MDS or DS
  • filehandle — Find commits for this file handle
  • init — 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)

Verifies the initial connection to the metadata server (MDS)/data server (DS). Then it verifies whether 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. it's giving thorough 👑

  • ipaddr — Destination IP address of MDS or DS
  • port — Destination port number of MDS or DS
  • ds — True if ipaddr/port defines a DS, otherwise MDS [default: False]
  • nocreate — 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 — DS index used for displaying purposes only [default: None]
  • exchid_status — Expected status for EXCHANGE_ID [default: 0]
  • cs_status — Expected status for CREATE_SESSION [default: 0]
  • Return the sessionid — and it's also stored in the object attribute sessionid. bestie keeps a copy, obviously 💖

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)

Verifies I/O is sent to the server specified by the ipaddr and port.

  • iomode — Verify reads (iomode == 1) or writes (iomode == 2)
  • stateid — Expected stateid to use in all I/O requests
  • ipaddr — Destination IP address of MDS or DS [default: do not match destination]
  • port — Destination port number of MDS or DS [default: do not match destination port]
  • proto — Protocol [default: self.proto]
  • src_ipaddr — Source IP address of request [default: do not match source]
  • filehandle — 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]
  • 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]
  • init — Initialized test variables [default: False]
  • maxindex — The match fails if packet index hits this limit [default: no limit]
  • pattern — Data pattern to compare [default: default data pattern]
  • Return the number of I/O operations sent to the server.

verify_layoutcommit(self, filehandle, filesize)

Verifies layoutcommit is properly sent to the server specified by the ipaddr for self.server and port given by self.port. Verifies a GETATTR asking for file size is sent within the same compound as the LAYOUTCOMMIT. Verifies GETATTR returns the correct size for the file. no cap, all three checks.

  • filehandle — Find layoutcommit for this file handle
  • filesize — Expected size of file

verify_layoutget(self, filehandle, iomode, riomode=None, status=0, offset=None, length=None, openfh={})

Verifies the client sends a LAYOUTGET for the given file handle.

  • filehandle — Find LAYOUTGET for this file handle
  • iomode — Expected I/O mode for LAYOUTGET call
  • riomode — 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
  • status — Expected status for LAYOUTGET reply [default: 0]
  • offset — Expected layout range for LAYOUTGET reply [default: None]
  • length — Expected layout range for LAYOUTGET reply [default: None]
  • openfh — 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)

Verifies layoutreturn is properly sent to the server specified by the ipaddr for self.server and port given by self.port.

  • layout_list — List of layouts

verify_pnfs_supported(self, filehandle, server_type, path=None, fstype=False)

Verifies 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. the way it digs through those bitmaps 🧚

verify_stripe(self, offset, size, ds_index)

Verifies 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.

  • offset — Real file offset
  • size — I/O size
  • ds_index — Data server index
  • Return True if stripe is correctly verified, False otherwise.

Static methods defined here

bitmap_str(bitmap, count, bmap, blist)

Returns the string representation of bitmap.

  • bitmap — Bitmap to convert
  • count — Number of occurrences of bitmap
  • bmap — Dictionary mapping the bits to strings
  • blist — List of all possible bit combinations

iomode_str(iomode)

Returns a string representation of iomode. This could be run as an instance or class method — flexible queen 💅

🌈 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. periodt. 💅✨

👑 AUTHOR 👑

Jorge Mora (mora@netapp.com)

and that's a wrap on the whole NFS_UTIL(3) page bestie 🫶 this was NFStest 3.2, dated 21 March 2023 — go forth and verify those packets, you absolute icon 💖🌸

📦 where this page comes from