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.

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

    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.

    ipaddr:
        Destination IP address [default: self.server_ipaddr]

    port:
        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.

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

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

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

    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)
Verify commits are properly sent to the server specified by the
given ipaddr and port.

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

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

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

    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={})
Verify 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)
Verify 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)
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.

    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)
Return 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)
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)