ryu/doc/source/library_packet.rst

   1 **************
   2 Packet library
   3 **************
   4
   5 Introduction
   6 ============
   7
   8 Ryu packet library helps you to parse and build various protocol
   9 packets. dpkt is the popular library for the same purpose, however it
  10 is not designed to handle protocols that are interleaved; vlan, mpls,
  11 gre, etc. So we implemented our own packet library.
  12
  13 Network Addresses
  14 =================
  15
  16 Unless otherwise specified, MAC/IPv4/IPv6 addresses are specified
  17 using human readable strings for this library.
  18 For example, '08:60:6e:7f:74:e7', '192.0.2.1', 'fe80::a60:6eff:fe7f:74e7'.
  19
  20 Parsing Packet
  21 ==============
  22
  23 First, let's look at how we can use the library to parse the received
  24 packets in a handler for OFPPacketIn messages.
  25
  26 .. code-block:: python
  27
  28     from ryu.lib.packet import packet
  29
  30     @handler.set_ev_cls(ofp_event.EventOFPPacketIn, handler.MAIN_DISPATCHER)
  31     def packet_in_handler(self, ev):
  32         pkt = packet.Packet(array.array('B', ev.msg.data))
  33         for p in pkt.protocols:
  34             print p
  35
  36 You can create a Packet class instance with the received raw
  37 data. Then the packet library parses the data and creates protocol
  38 class instances included the data. The packet class 'protocols' has
  39 the protocol class instances.
  40
  41 If a TCP packet is received, something like the following is printed::
  42
  43     <ryu.lib.packet.ethernet.ethernet object at 0x107a5d790>
  44     <ryu.lib.packet.vlan.vlan object at 0x107a5d7d0>
  45     <ryu.lib.packet.ipv4.ipv4 object at 0x107a5d810>
  46     <ryu.lib.packet.tcp.tcp object at 0x107a5d850>
  47
  48 If vlan is not used, you see something like::
  49
  50     <ryu.lib.packet.ethernet.ethernet object at 0x107a5d790>
  51     <ryu.lib.packet.ipv4.ipv4 object at 0x107a5d810>
  52     <ryu.lib.packet.tcp.tcp object at 0x107a5d850>
  53
  54 You can access to a specific protocol class instance by using the
  55 packet class iterator.  Let's try to check VLAN id if VLAN is used:
  56
  57 .. code-block:: python
  58
  59     from ryu.lib.packet import packet
  60
  61     @handler.set_ev_cls(ofp_event.EventOFPPacketIn, handler.MAIN_DISPATCHER)
  62     def packet_in_handler(self, ev):
  63         pkt = packet.Packet(array.array('B', ev.msg.data))
  64         for p in pkt:
  65             print p.protocol_name, p
  66             if p.protocol_name == 'vlan':
  67                 print 'vid = ', p.vid
  68
  69 You see something like::
  70
  71     ethernet <ryu.lib.packet.ethernet.ethernet object at 0x107a5d790>
  72     vlan <ryu.lib.packet.vlan.vlan object at 0x107a5d7d0>
  73     vid = 10
  74     ipv4 <ryu.lib.packet.ipv4.ipv4 object at 0x107a5d810>
  75     tcp <ryu.lib.packet.tcp.tcp object at 0x107a5d850>
  76
  77
  78
  79 Building Packet
  80 ===============
  81
  82 You need to create protocol class instances that you want to send, add
  83 them to a packet class instance via add_protocol method, and then call
  84 serialize method. You have the raw data to send. The following example
  85 is building an arp packet.
  86
  87 .. code-block:: python
  88
  89     from ryu.ofproto import ether
  90     from ryu.lib.packet import ethernet, arp, packet
  91
  92     e = ethernet.ethernet(dst='ff:ff:ff:ff:ff:ff',
  93                           src='08:60:6e:7f:74:e7',
  94                           ethertype=ether.ETH_TYPE_ARP)
  95     a = arp.arp(hwtype=1, proto=0x0800, hlen=6, plen=4, opcode=2,
  96                 src_mac='08:60:6e:7f:74:e7', src_ip='192.0.2.1',
  97                 dst_mac='00:00:00:00:00:00', dst_ip='192.0.2.2')
  98     p = packet.Packet()
  99     p.add_protocol(e)
 100     p.add_protocol(a)
 101     p.serialize()
 102     print repr(p.data)  # the on-wire packet