PACKET.PKTT(1)packet.pktt 1.0.1 PACKET.PKTT(1)NAMEpacket.pktt - Packet trace module
DESCRIPTION
The Packet trace module is a python module that takes a trace file cre‐
ated by tcpdump and unpacks the contents of each packet. You can decode
one packet at a time, or do a search for specific packets. The main
difference between this modules and other tools used to decode trace
files is that you can use this module to completely automate your
tests.
How does it work? It opens the trace file and reads one record at a
time keeping track where each record starts. This way, very large trace
files can be opened without having to wait for the file to load and
avoid loading the whole file into memory.
Packet layers supported:
- ETHERNET II (RFC 894)
- IP layer (only supports v4)
- TCP layer
- RPC layer
- NFS v4.0
- NFS v4.1 including pNFS file layouts
CLASSES
class Pktt(baseobj.BaseObj, packet.unpack.Unpack)
Packet trace object
Usage:
from packet.pktt import Pktt
x = Pktt("/traces/tracefile.cap")
# Iterate over all packets found in the trace file
for pkt in x:
print pkt
Methods defined here:
---------------------
__contains__(self, expr)
Implement membership test operator. Return true if expr matches
a packet in the trace file, false otherwise.
The packet is also stored in the object attribute pkt.
Examples:
# Find the next READ request
if ("NFS.argop == 25" in x):
print x.pkt.nfs
See match() method for more information
__del__(self)
Destructor
Gracefully close the tcpdump trace file if it is opened.
__getitem__(self, index)
Get the packet from the trace file given by the index or raise
IndexError.
The packet is also stored in the object attribute pkt.
Examples:
pkt = x[index]
__init__(self, tfile, live=False, state=True)
Constructor
Initialize object's private data, note that this will not check
the file for existence nor will open the file to verify if it is
a valid tcpdump file. The tcpdump trace file will be opened the
first time a packet is retrieved.
tracefile:
Name of tcpdump trace file (little or big endian format)
live: If set to True, methods will not return if encountered
<EOF>, they will keep on trying until more data is avail‐
able in the file. This is useful when running tcpdump in
parallel, especially when tcpdump is run with the '-C'
option, in which case when <EOF> is encountered the next
trace file created by tcpdump will be opened and the
object will be re-initialized, all private data referenc‐
ing the previous file is lost.
__iter__(self)
Make this object iterable.
match(self, expr, maxindex=None)
Return the packet that matches the given expression, also the
packet index points to the next packet after the matched packet.
Returns None if packet is not found and the packet index points
to the packet at the beginning of the search.
expr: String of expressions to be evaluated
maxindex:
The match fails if packet index hits this limit
Examples:
# Find the packet with both the ACK and SYN TCP flags set to
1
pkt = x.match("TCP.flags.ACK == 1 and TCP.flags.SYN == 1")
# Find the next NFS EXCHANGE_ID request
pkt = x.match("NFS.argop == 42")
# Find the next NFS OPEN request or reply
pkt = x.match("NFS.op == 18")
# Find all packets coming from subnet 192.168.1.0/24 using
# a regular expression
while x.match(r"IP.src == re('192.168.1.*')"):
print x.pkt.tcp
# Find packet having a GETATTR asking for FATTR4_FS_LAY‐
OUT_TYPE(bit 62)
pkt_call = x.match("NFS.attr_request & 0x4000000000000000L
!= 0")
if pkt_call:
# Find GETATTR reply
xid = pkt_call.rpc.xid
# Find reply where the number 62 is in the array
NFS.obj_attributes
pkt_reply = x.match("RPC.xid == %d and 62 in
NFS.obj_attributes" % xid)
# Find the next WRITE request
pkt = x.match("NFS.argop == 38")
if pkt:
print pkt.nfs
# Same as above, but using membership test operator instead
if ("NFS.argop == 38" in x):
print x.pkt.nfs
See also:
match_ethernet(), match_ip(), match_tcp(), match_rpc(),
match_nfs()
match_ethernet(self, args)
Match ETHERNET values on current packet.
See ETHERNET() object for more information
match_ip(self, args)
Match IP values on current packet.
See IPv4() and IPv6() object for more information
match_nfs(self, args)
Match NFS values on current packet.
In NFSv4, there is a single compound procedure with multiple
operations, matching becomes a little bit tricky in order to
make the matching expression easy to use. The NFS object's name
space gets converted into a flat name space for the sole purpose
of matching. In other words, all operation objects in argarray
or resarray are treated as being part of the NFS object's top
level attributes.
Consider the following NFS object:
nfsobj = COMPOUND4res(
status=NFS4_OK,
tag='NFSv4_tag',
resarray=[
nfs_resop4(
resop=OP_SEQUENCE,
opsequence=SEQUENCE4res(
sr_status=NFS4_OK,
sr_resok4=SEQUENCE4resok(
sr_sessionid='sessionid',
sr_sequenceid=25,
sr_slotid=0,
sr_highest_slotid=0,
sr_target_highest_slotid=15,
sr_status_flags=0,
)
)
),
nfs_resop4(
resop=OP_PUTFH,
opputfh=PUTFH4res(
status=NFS4_OK
)
),
...
]
),
The result for operation PUTFH is the second in the list:
putfh = nfsobj.resarray[1]
From this putfh object the status operation can be accessed as:
status = putfh.opputfh.status
or simply as (this is how the NFS object works):
status = putfh.status
In this example, the following match expression 'NFS.status ==
0' could match the top level status of the compound (nfsobj.sta‐
tus) or the putfh status (nfsobj.resarray[1].status)
The following match expression 'NFS.sr_sequenceid == 25' will
also match this packet as well, even though the actual expres‐
sion should be 'nfsobj.resarray[0].opse‐
quence.sr_resok4.sr_sequenceid == 25' or simply 'nfsobj.resar‐
ray[0].sr_sequenceid == 25'.
This approach makes the match expressions simpler at the expense
of having some ambiguities on where the actual matched occurred.
If a match is desired on a specific operation, a more qualified
name can be given. In the above example, in order to match the
status of the PUTFH operation the match expression
'NFS.opputfh.status == 0' can be used. On the other hand, con‐
sider a compound having multiple PUTFH results the above match
expression will always match the first occurrence of PUTFH where
the status is 0. There is no way to tell the match engine to
match the second or Nth occurrence of an operation.
match_rpc(self, args)
Match RPC values on current packet.
See RPC() object for more information
match_tcp(self, args)
Match TCP values on current packet.
See TCP() object for more information
next(self)
Get the next packet from the trace file or raise StopIteration.
The packet is also stored in the object attribute pkt.
Examples:
# Iterate over all packets found in the trace file using
# the iterable properties of the object
for pkt in x:
print pkt
# Iterate over all packets found in the trace file using it
# as a method and using the object variable as the packet
# Must use the try statement to catch StopIteration excep‐
tion
try:
while (x.next()):
print x.pkt
except StopIteration:
pass
# Iterate over all packets found in the trace file using it
# as a method and using the return value as the packet
# Must use the try statement to catch StopIteration excep‐
tion
while True:
try:
print x.next()
except StopIteration:
break
NOTE:
Supports only single active iteration
rewind(self, index=0)
Rewind the trace file by setting the file pointer to the start
of the given packet index. Returns False if unable to rewind the
file, e.g., when the given index is greater than the maximum
number of packets processed so far.
Static methods defined here:
----------------------------
escape(data)
Escape special characters.
Examples:
# Call as an instance
escaped_data = x.escape(data)
# Call as a class
escaped_data = Pktt.escape(data)
ip_tcp_dst_expr(ipaddr, port)
Return a match expression to find a packet going to ipaddr:port.
Examples:
# Call as an instance
expr = x.ip_tcp_dst_expr('192.168.1.50', 2049)
# Call as a class
expr = Pktt.ip_tcp_dst_expr('192.168.1.50', 2049)
# Returns "IP.dst == '192.168.1.50' and TCP.dst_port ==
2049"
# Expression ready for x.match()
pkt = x.match(expr)
ip_tcp_src_expr(ipaddr, port)
Return a match expression to find a packet coming from
ipaddr:port.
Examples:
# Call as an instance
expr = x.ip_tcp_src_expr('192.168.1.50', 2049)
# Call as a class
expr = Pktt.ip_tcp_src_expr('192.168.1.50', 2049)
# Returns "IP.src == '192.168.1.50' and TCP.src_port ==
2049"
# Expression ready for x.match()
pkt = x.match(expr)SEE ALSObaseobj(1), packet.link.ethernet(1), packet.pkt(1), packet.record(1),
packet.unpack(1)BUGS
No known bugs.
AUTHOR
Jorge Mora (mora@netapp.com)
NFStest 1.0.2 10 April 2013 PACKET.PKTT(1)
