Ryu 1.8 documentation

Packet library API Reference

«  Packet library   ::   Contents   ::   OF-Config support  »

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

«  Packet library   ::   Contents   ::   OF-Config support  »