Packet library API Reference¶
Packet class¶
- class ryu.lib.packet.packet.Packet(data=None)¶
A packet decoder/encoder class.
An instance is used to either decode or encode a single packet.
data is a bytearray to describe a raw datagram to decode. When decoding, a Packet object is iteratable. Iterated values are protocol (ethernet, ipv4, ...) headers and the payload. Protocol headers are instances of subclass of packet_base.PacketBase. The payload is a bytearray. They are iterated in on-wire order.
data should be omitted when encoding a packet.
- add_protocol(proto)¶
Register a protocol proto for this packet.
This method is legal only when encoding a packet.
When encoding a packet, register a protocol (ethernet, ipv4, ...) header to add to this packet. Protocol headers should be registered in on-wire order before calling self.serialize.
- serialize()¶
Encode a packet and store the resulted bytearray in self.data.
This method is legal only when encoding a packet.
Protocol Header classes¶
- class ryu.lib.packet.packet_base.PacketBase¶
A base class for a protocol (ethernet, ipv4, ...) header.
- classmethod get_packet_type(type_)¶
Per-protocol dict-like get method.
Provided for convenience of protocol implementers. Internal use only.
- classmethod parser(buf)¶
Decode a protocol header.
This method is used only when decoding a packet.
Decode a protocol header at offset 0 in bytearray buf. Returns the following two objects.
An object to describe the decoded header. It should have the following attributes at least.
Attribute
Description
length
The number of the corresponding on-wire octets.
A packet_base.PacketBase subclass appropriate for the rest of the packet. None when the rest of the packet should be considered as raw payload.
- classmethod register_packet_type(cls_, type_)¶
Per-protocol dict-like set method.
Provided for convenience of protocol implementers. Internal use only.
- serialize(payload, prev)¶
Encode a protocol header.
This method is used only when encoding a packet.
Encode a protocol header. Returns a bytearray which contains the header.
payload is the rest of the packet which will immediately follow this header.
prev is a packet_base.PacketBase subclass for the outer protocol header. prev is None if the current header is the outer-most. For example, prev is ipv4 or ipv6 for tcp.serialize.
- class ryu.lib.packet.ethernet.ethernet(dst, src, ethertype)¶
Ethernet header encoder/decoder class.
An instance has the following attributes at least. __init__ takes the correspondig args in this order.
Attribute Description dst destination address src source address ethertype ether type
- class ryu.lib.packet.vlan.vlan(pcp, cfi, vid, ethertype)¶
VLAN (IEEE 802.1Q) header encoder/decoder class.
An instance has the following attributes at least. Most of them are same to the on-wire counterparts but in host byte order. __init__ takes the correspondig args in this order.
Attribute Description pcp Priority Code Point cfi Canonical Format Indicator vid VLAN Identifier ethertype EtherType
- class ryu.lib.packet.mpls.mpls(label, exp, bsb, ttl)¶
MPLS (RFC 3032) header encoder/decoder class.
NOTE: When decoding, this implementation assumes that the inner protocol is IPv4.
An instance has the following attributes at least. Most of them are same to the on-wire counterparts but in host byte order. __init__ takes the correspondig args in this order.
Attribute Description label Label Value exp Experimental Use bsb Bottom of Stack ttl Time To Live
- class ryu.lib.packet.arp.arp(hwtype, proto, hlen, plen, opcode, src_mac, src_ip, dst_mac, dst_ip)¶
ARP (RFC 826) header encoder/decoder class.
An instance has the following attributes at least. Most of them are same to the on-wire counterparts but in host byte order. __init__ takes the correspondig args in this order.
Attribute Description hwtype ar$hrd proto ar$pro hlen ar$hln plen ar$pln opcode ar$op src_mac ar$sha src_ip ar$spa dst_mac ar$tha dst_ip ar$tpa
- ryu.lib.packet.arp.arp_ip(opcode, src_mac, src_ip, dst_mac, dst_ip)¶
A convenient wrapper for IPv4 ARP for Ethernet.
This is an equivalent of the following code.
arp(ARP_HW_TYPE_ETHERNET, ether.ETH_TYPE_IP, 6, 4, opcode, src_mac, src_ip, dst_mac, dst_ip)
- class ryu.lib.packet.ipv4.ipv4(version, header_length, tos, total_length, identification, flags, offset, ttl, proto, csum, src, dst, option=None)¶
IPv4 (RFC 791) header encoder/decoder class.
NOTE: When decoding, this implementation tries to decode the upper layer protocol even for a fragmented datagram. It isn’t likely what a user would want.
An instance has the following attributes at least. Most of them are same to the on-wire counterparts but in host byte order. __init__ takes the correspondig args in this order.
Attribute Description version Version header_length IHL tos Type of Service total_length Total Length (0 means automatically-calculate when encoding) identification Identification flags Flags offset Fragment Offset ttl Time to Live proto Protocol csum Header Checksum (Ignored and automatically-calculated when encoding) src Source Address dst Destination Address option A bytearray which contains the entire Options, or None for no Options
- class ryu.lib.packet.icmp.echo(id_, seq, data=None)¶
ICMP sub encoder/decoder class for Echo and Echo Reply messages.
This is used with ryu.lib.packet.icmp.icmp for ICMP Echo and Echo Reply messages.
An instance has the following attributes at least. Most of them are same to the on-wire counterparts but in host byte order. __init__ takes the correspondig args in this order.
Attribute Description id Identifier seq Sequence Number data Internet Header + 64 bits of Original Data Datagram
- class ryu.lib.packet.icmp.icmp(type_, code, csum, data=None)¶
ICMP (RFC 792) header encoder/decoder class.
An instance has the following attributes at least. Most of them are same to the on-wire counterparts but in host byte order. __init__ takes the correspondig args in this order.
Attribute Description type Type code Code csum CheckSum (0 means automatically-calculate when encoding) data Payload. Either a bytearray or ryu.lib.packet.icmp.echo object. NOTE: This includes “unused” 16 bits and the following “Internet Header + 64 bits of Original Data Datagram” of the ICMP header.
- class ryu.lib.packet.ipv6.ipv6(version, traffic_class, flow_label, payload_length, nxt, hop_limit, src, dst)¶
IPv6 (RFC 2460) header encoder/decoder class.
An instance has the following attributes at least. Most of them are same to the on-wire counterparts but in host byte order. __init__ takes the correspondig args in this order.
Attribute Description version Version traffic_class Traffic Class flow_label When decoding, Flow Label. When encoding, the most significant 8 bits of Flow Label. payload_length Payload Length nxt Next Header hop_limit Hop Limit src Source Address dst Destination Address
- class ryu.lib.packet.icmpv6.echo(id_, seq, data=None)¶
ICMPv6 sub encoder/decoder class for Echo Request and Echo Reply messages.
This is used with ryu.lib.packet.icmpv6.icmpv6 for ICMPv6 Echo Request and Echo Reply messages.
An instance has the following attributes at least. Most of them are same to the on-wire counterparts but in host byte order. __init__ takes the correspondig args in this order.
Attribute Description id Identifier seq Sequence Number data Data
- class ryu.lib.packet.icmpv6.icmpv6(type_, code, csum, data=None)¶
ICMPv6 (RFC 2463) header encoder/decoder class.
An instance has the following attributes at least. Most of them are same to the on-wire counterparts but in host byte order. __init__ takes the correspondig args in this order.
Attribute Description type_ Type code Code csum CheckSum (0 means automatically-calculate when encoding) data Payload. ryu.lib.packet.icmpv6.echo object, or ryu.lib.packet.icmpv6.nd_neighbor object, or a bytearray.
- class ryu.lib.packet.icmpv6.nd_neighbor(res, dst, type_=None, length=None, data=None)¶
ICMPv6 sub encoder/decoder class for Neighbor Solicitation and Neighbor Advertisement messages. (RFC 4861)
This is used with ryu.lib.packet.icmpv6.icmpv6.
An instance has the following attributes at least. Most of them are same to the on-wire counterparts but in host byte order. __init__ takes the correspondig args in this order.
Attribute Description res R,S,O Flags for Neighbor Advertisement. The 3 MSBs of “Reserved” field for Neighbor Solicitation. dst Target Address type_ “Type” field of the first option. None if no options. NOTE: This implementation doesn’t support two or more options. length “Length” field of the first option. None if no options. data An object to describe the first option. None if no options. Either ryu.lib.packet.icmpv6.nd_option_la object or a bytearray.
- class ryu.lib.packet.icmpv6.nd_option_la(hw_src, data=None)¶
ICMPv6 sub encoder/decoder class for Neighbor discovery Source/Target Link-Layer Address Option. (RFC 4861)
This is used with ryu.lib.packet.icmpv6.nd_neighbor.
An instance has the following attributes at least. Most of them are same to the on-wire counterparts but in host byte order. __init__ takes the correspondig args in this order.
Attribute Description hw_src Link-Layer Address. NOTE: If the address is longer than 6 octets this contains the first 6 octets in the address. This implementation assumes the address has at least 6 octets. data A bytearray which contains the rest of Link-Layer Address and padding. When encoding a packet, it’s user’s responsibility to provide necessary padding for 8-octets alignment required by the protocol.
- class ryu.lib.packet.tcp.tcp(src_port, dst_port, seq, ack, offset, bits, window_size, csum, urgent, option=None)¶
TCP (RFC 793) header encoder/decoder class.
An instance has the following attributes at least. Most of them are same to the on-wire counterparts but in host byte order. __init__ takes the correspondig args in this order.
Attribute Description src_port Source Port dst_port Destination Port seq Sequence Number ack Acknowledgement Number offset Data Offset bits Control Bits window_size Window csum Checksum (0 means automatically-calculate when encoding) urgent Urgent Pointer option An bytearray containing Options and following Padding. None if no options.
- class ryu.lib.packet.udp.udp(src_port, dst_port, total_length=0, csum=0)¶
UDP (RFC 768) header encoder/decoder class.
An instance has the following attributes at least. Most of them are same to the on-wire counterparts but in host byte order. __init__ takes the correspondig args in this order.
Attribute Description src_port Source Port dst_port Destination Port total_length Length (0 means automatically-calculate when encoding) csum Checksum (0 means automatically-calculate when encoding)
- class ryu.lib.packet.vrrp.vrrp(version, type_, vrid, priority, count_ip, max_adver_int, checksum, ip_addresses, auth_type=None, auth_data=None)¶
The base class for VRRPv2 (RFC 3768) and VRRPv3 (RFC 5798) header encoder/decoder classes.
Unlike other ryu.lib.packet.packet_base.PacketBase derived classes, This class should not be directly instantiated by user.
An instance has the following attributes at least. Most of them are same to the on-wire counterparts but in host byte order.
Attribute Description version Version type Type vrid Virtual Rtr ID (VRID) priority Priority count_ip Count IPvX Addr. Calculated automatically when encoding. max_adver_int Maximum Advertisement Interval (Max Adver Int) checksum Checksum. Calculated automatically when encoding. ip_addresses IPvX Address(es). A python list of IP addresses. auth_type Authentication Type (only for VRRPv2) auth_data Authentication Data (only for VRRPv2) - create_packet(primary_ip_address, vlan_id=None)¶
Prepare a VRRP packet.
Returns a newly created ryu.lib.packet.packet.Packet object with appropriate protocol header objects added by add_protocol(). It’s caller’s responsibility to serialize(). The serialized packet would looks like the ones described in the following sections.
- RFC 3768 5.1. VRRP Packet Format
- RFC 5798 5.1. VRRP Packet Format
Argument Description primary_ip_address Source IP address vlan_id VLAN ID. None for no VLAN.
- class ryu.lib.packet.vrrp.vrrpv2(version, type_, vrid, priority, count_ip, max_adver_int, checksum, ip_addresses, auth_type=None, auth_data=None)¶
VRRPv2 (RFC 3768) header encoder/decoder class.
Unlike other ryu.lib.packet.packet_base.PacketBase derived classes, create method should be used to instantiate an object of this class.
- static create(type_, vrid, priority, max_adver_int, ip_addresses)¶
Unlike other ryu.lib.packet.packet_base.PacketBase derived classes, this method should be used to instantiate an object of this class.
This method’s arguments are same as ryu.lib.packet.vrrp.vrrp object’s attributes of the same name. (except that type_ corresponds to type attribute.)
- class ryu.lib.packet.vrrp.vrrpv3(version, type_, vrid, priority, count_ip, max_adver_int, checksum, ip_addresses, auth_type=None, auth_data=None)¶
VRRPv3 (RFC 5798) header encoder/decoder class.
Unlike other ryu.lib.packet.packet_base.PacketBase derived classes, create method should be used to instantiate an object of this class.
- static create(type_, vrid, priority, max_adver_int, ip_addresses)¶
Unlike other ryu.lib.packet.packet_base.PacketBase derived classes, this method should be used to instantiate an object of this class.
This method’s arguments are same as ryu.lib.packet.vrrp.vrrp object’s attributes of the same name. (except that type_ corresponds to type attribute.)