From f3e931b03fe2839d2f512c37b7be05944078b2e2 Mon Sep 17 00:00:00 2001 From: IWASE Yusuke Date: Mon, 30 May 2016 15:24:44 +0900 Subject: [PATCH] doc: Add PCAP file library reference Signed-off-by: IWASE Yusuke Signed-off-by: FUJITA Tomonori --- doc/source/library.rst | 1 + doc/source/library_pcap.rst | 27 +++++++++ ryu/lib/pcaplib.py | 113 +++++++++++++++++++++--------------- 3 files changed, 95 insertions(+), 46 deletions(-) create mode 100644 doc/source/library_pcap.rst diff --git a/doc/source/library.rst b/doc/source/library.rst index bc8ff67f..ccdcae30 100644 --- a/doc/source/library.rst +++ b/doc/source/library.rst @@ -9,6 +9,7 @@ Ryu provides some useful library for your network applications. library_packet.rst library_packet_ref.rst + library_pcap.rst library_of_config.rst library_bgp_speaker.rst library_bgp_speaker_ref.rst diff --git a/doc/source/library_pcap.rst b/doc/source/library_pcap.rst new file mode 100644 index 00000000..2eb3fe5e --- /dev/null +++ b/doc/source/library_pcap.rst @@ -0,0 +1,27 @@ +***************** +PCAP file library +***************** + +Introduction +============ + +Ryu PCAP file library helps you to read/write PCAP file which file +format are described in `The Wireshark Wiki`_. + +.. _The Wireshark Wiki: https://wiki.wireshark.org/Development/LibpcapFileFormat + +Reading PCAP file +================= + +For loading the packet data containing in PCAP files, you can use +pcaplib.Reader. + +.. autoclass:: ryu.lib.pcaplib.Reader + +Writing PCAP file +================= + +For dumping the packet data which your RyuApp received, you can use +pcaplib.Writer. + +.. autoclass:: ryu.lib.pcaplib.Writer diff --git a/ryu/lib/pcaplib.py b/ryu/lib/pcaplib.py index b11c0b35..8b7400bf 100644 --- a/ryu/lib/pcaplib.py +++ b/ryu/lib/pcaplib.py @@ -33,52 +33,8 @@ Reference source: http://wiki.wireshark.org/Development/LibpcapFileFormat +---------------------+ | Packet Data | +---------------------+ - | ... - +---------------- ... - - -Sample usage of dump packets: - - from ryu.lib import pcaplib - - class SimpleSwitch13(app_manager.RyuApp): - OFP_VERSIONS = [ofproto_v1_3.OFP_VERSION] - - def __init__(self, *args, **kwargs): - super(SimpleSwitch13, self).__init__(*args, **kwargs) - self.mac_to_port = {} - - # Creating an instance with a PCAP filename - self.pcap_pen = Writer(open('mypcap.pcap', 'wb')) - - @set_ev_cls(ofp_event.EventOFPPacketIn, MAIN_DISPATCHER) - def _packet_in_handler(self, ev): - msg = ev.msg - - # Dump the data packet into PCAP file - self.pcap_pen.write_pkt(msg.data) - - pkt = packet.Packet(msg.data) - -Sample usage of reading PCAP files: - - from ryu.lib import pcaplib - from ryu.lib.packet import packet - - frame_count = 0 - # Using the Reader iterator that yields packets in PCAP file - for ts, buf in pcaplib.Reader(open('test.pcap', 'rb')): - frame_count += 1 - pkt = packet.Packet(buf) - - eth = pkt.get_protocols(ethernet.ethernet)[0] - - dst = eth.dst - src = eth.src - # print frames count, timestamp, ethernet src, ethernet dst - # and raw packet. - print frame_count, ts, dst, src, pkt - + | ... | + +---------------------+ """ import struct @@ -235,6 +191,30 @@ class PcapPktHdr(object): class Reader(object): + """ + PCAP file reader + + ================ =================================== + Argument Description + ================ =================================== + file_obj File object which reading PCAP file + in binary mode + ================ =================================== + + Example of usage:: + + from ryu.lib import pcaplib + from ryu.lib.packet import packet + + frame_count = 0 + # iterate pcaplib.Reader that yields (timestamp, packet_data) + # in the PCAP file + for ts, buf in pcaplib.Reader(open('test.pcap', 'rb')): + frame_count += 1 + pkt = packet.Packet(buf) + print("%d, %f, %s" % (frame_count, ts, pkt)) + """ + def __init__(self, file_obj): self._fp = file_obj buf = self._fp.read(PcapFileHdr.FILE_HDR_SIZE) @@ -264,6 +244,47 @@ class Reader(object): class Writer(object): + """ + PCAP file writer + + ========== ================================================== + Argument Description + ========== ================================================== + file_obj File object which writing PCAP file in binary mode + snaplen Max length of captured packets (in octets) + network Data link type. (e.g. 1 for Ethernet, + see `tcpdump.org`_ for details) + ========== ================================================== + + .. _tcpdump.org: http://www.tcpdump.org/linktypes.html + + Example of usage:: + + ... + from ryu.lib import pcaplib + + + class SimpleSwitch13(app_manager.RyuApp): + OFP_VERSIONS = [ofproto_v1_3.OFP_VERSION] + + def __init__(self, *args, **kwargs): + super(SimpleSwitch13, self).__init__(*args, **kwargs) + self.mac_to_port = {} + + # Create pcaplib.Writer instance with a file object + # for the PCAP file + self.pcap_writer = pcaplib.Writer(open('mypcap.pcap', 'wb')) + + ... + + @set_ev_cls(ofp_event.EventOFPPacketIn, MAIN_DISPATCHER) + def _packet_in_handler(self, ev): + # Dump the packet data into PCAP file + self.pcap_writer.write_pkt(ev.msg.data) + + ... + """ + def __init__(self, file_obj, snaplen=65535, network=1): self._f = file_obj self.snaplen = snaplen