Packet library API Reference

Packet class

Stream Parser class

class ryu.lib.packet.stream_parser.StreamParser

Streaming parser base class.

An instance of a subclass of this class is used to extract messages from a raw byte stream.

It’s designed to be used for data read from a transport which doesn’t preserve message boundaries. A typical example of such a transport is TCP.

exception TooSmallException
parse(data)

Tries to extract messages from a raw byte stream.

The data argument would be python bytes newly read from the input stream.

Returns an ordered list of extracted messages. It can be an empty list.

The rest of data which doesn’t produce a complete message is kept internally and will be used when more data is come. I.e. next time this method is called again.

try_parse(q)

Try to extract a message from the given bytes.

This is an override point for subclasses.

This method tries to extract a message from bytes given by the argument.

Raises TooSmallException if the given data is not enough to extract a complete message but there’s still a chance to extract a message if more data is come later.

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 three objects.

  • An object to describe the decoded header.
  • 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.
  • The rest of packet.
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.

ryu.lib.packet.mpls.label_from_bin(buf)

Converts binary representation label to integer.

Parameters:buf – Binary representation of label.
Returns:MPLS Label and BoS bit.
ryu.lib.packet.mpls.label_to_bin(mpls_label, is_bos=True)

Converts integer label to binary representation.

Parameters:
  • mpls_label – MPLS Label.
  • is_bos – BoS bit.
Returns:

Binary representation of label.
class ryu.lib.packet.mpls.mpls(label=0, exp=0, bsb=1, ttl=255)

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 corresponding args in this order.

Attribute Description
label Label Value
exp Experimental Use
bsb Bottom of Stack
ttl Time To Live
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 three objects.

  • An object to describe the decoded header.
  • 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.
  • The rest of packet.
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.arp.arp(hwtype=1, proto=2048, hlen=6, plen=4, opcode=1, src_mac='ff:ff:ff:ff:ff:ff', src_ip='0.0.0.0', dst_mac='ff:ff:ff:ff:ff:ff', dst_ip='0.0.0.0')

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. IPv4 addresses are represented as a string like ‘192.0.2.1’. MAC addresses are represented as a string like ‘08:60:6e:7f:74:e7’. __init__ takes the corresponding args in this order.

Attribute Description Example
hwtype ar$hrd  
proto ar$pro  
hlen ar$hln  
plen ar$pln  
opcode ar$op  
src_mac ar$sha ‘08:60:6e:7f:74:e7’
src_ip ar$spa ‘192.0.2.1’
dst_mac ar$tha ‘00:00:00:00:00:00’
dst_ip ar$tpa ‘192.0.2.2’
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 three objects.

  • An object to describe the decoded header.
  • 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.
  • The rest of packet.
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.

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.icmp.TimeExceeded(data_len=0, data=None)

ICMP sub encoder/decoder class for Time Exceeded Message.

This is used with ryu.lib.packet.icmp.icmp for ICMP Time Exceeded Message.

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 corresponding args in this order.

[RFC4884] introduced 8-bit data length attribute.

Attribute Description
data_len data length
data Internet Header + leading octets of original datagram
class ryu.lib.packet.icmp.dest_unreach(data_len=0, mtu=0, data=None)

ICMP sub encoder/decoder class for Destination Unreachable Message.

This is used with ryu.lib.packet.icmp.icmp for ICMP Destination Unreachable Message.

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 corresponding args in this order.

[RFC1191] reserves bits for the “Next-Hop MTU” field. [RFC4884] introduced 8-bit data length attribute.

Attribute Description
data_len data length
mtu

Next-Hop MTU

NOTE: This field is required when icmp code is 4

code 4 = fragmentation needed and DF set
data Internet Header + leading octets of original datagram
class ryu.lib.packet.icmp.echo(id_=0, seq=0, 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 corresponding 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_=8, code=0, csum=0, 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 corresponding 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 or ryu.lib.packet.icmp.dest_unreach or ryu.lib.packet.icmp.TimeExceeded object NOTE for icmp.echo: This includes “unused” 16 bits and the following “Internet Header + 64 bits of Original Data Datagram” of the ICMP header. NOTE for icmp.dest_unreach and icmp.TimeExceeded: This includes “unused” 8 or 24 bits and the following “Internet Header + leading octets of original datagram” of the original packet.
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 three objects.

  • An object to describe the decoded header.
  • 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.
  • The rest of packet.
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.

ryu.lib.packet.vxlan.vni_from_bin(buf)

Converts binary representation VNI to integer.

Parameters:buf – binary representation of VNI.
Returns:VNI integer.
ryu.lib.packet.vxlan.vni_to_bin(vni)

Converts integer VNI to binary representation.

Parameters:vni – integer of VNI
Returns:binary representation of VNI.
class ryu.lib.packet.vxlan.vxlan(vni)

VXLAN (RFC 7348) 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 corresponding args in this order.

Attribute Description
vni VXLAN Network Identifier
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 three objects.

  • An object to describe the decoded header.
  • 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.
  • The rest of packet.
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.

Geneve packet parser/serializer

class ryu.lib.packet.geneve.Option(option_class=None, type_=None, length=0)

Tunnel Options

class ryu.lib.packet.geneve.OptionDataUnknown(buf, option_class=None, type_=None, length=0)

Unknown Option Class and Type specific Option

class ryu.lib.packet.geneve.geneve(version=0, opt_len=0, flags=0, protocol=25944, vni=None, options=None)

Geneve (RFC draft-ietf-nvo3-geneve-03) 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 corresponding args in this order.

Attribute Description
version Version.
opt_len The length of the options fields.
flags Flag field for OAM packet and Critical options present.
protocol Protocol Type field. The Protocol Type is defined as “ETHER TYPES”.
vni Identifier for unique element of virtual network.
options List of Option* instance.
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 three objects.

  • An object to describe the decoded header.
  • 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.
  • The rest of packet.
serialize(payload=None, prev=None)

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.udp.udp(src_port=1, dst_port=1, 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 corresponding 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)
static get_packet_type(src_port, dst_port)

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 three objects.

  • An object to describe the decoded header.
  • 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.
  • The rest of packet.
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.

DHCP packet parser/serializer

class ryu.lib.packet.dhcp.dhcp(op, chaddr, options=None, htype=1, hlen=0, hops=0, xid=None, secs=0, flags=0, ciaddr='0.0.0.0', yiaddr='0.0.0.0', siaddr='0.0.0.0', giaddr='0.0.0.0', sname='', boot_file='')

DHCP (RFC 2131) header encoder/decoder class.

The serialized packet would looks like the ones described in the following sections.

  • RFC 2131 DHCP packet format

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 corresponding args in this order.

Attribute Description
op Message op code / message type. 1 = BOOTREQUEST, 2 = BOOTREPLY
htype Hardware address type (e.g. ‘1’ = 10mb ethernet).
hlen Hardware address length (e.g. ‘6’ = 10mb ethernet).
hops Client sets to zero, optionally used by relay agent when booting via a relay agent.
xid Transaction ID, a random number chosen by the client, used by the client and serverto associate messages and responses between a client and a server.
secs Filled in by client, seconds elapsed since client began address acquisition or renewal process.
flags Flags.
ciaddr Client IP address; only filled in if client is in BOUND, RENEW or REBINDING state and can respond to ARP requests.
yiaddr ‘your’ (client) IP address.
siaddr IP address of next server to use in bootstrap; returned in DHCPOFFER, DHCPACK by server.
giaddr Relay agent IP address, used in booting via a relay agent.
chaddr Client hardware address.
sname Optional server host name, null terminated string.
boot_file Boot file name, null terminated string; “generic” name or null in DHCPDISCOVER, fully qualified directory-path name in DHCPOFFER.
options Optional parameters field (‘DHCP message type’ option must be included in every DHCP message).
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 three objects.

  • An object to describe the decoded header.
  • 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.
  • The rest of packet.
serialize(_payload=None, _prev=None)

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.dhcp.option(tag, value, length=0)

DHCP (RFC 2132) options encoder/decoder class.

This is used with ryu.lib.packet.dhcp.dhcp.options.

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 corresponding args in this order.

Attribute Description
tag Option type. (except for the ‘magic cookie’, ‘pad option’ and ‘end option’.)
value Option’s value. (set the value that has been converted to hexadecimal.)
length Option’s value length. (calculated automatically from the length of value.)
class ryu.lib.packet.dhcp.options(option_list=None, options_len=0, magic_cookie='99.130.83.99')

DHCP (RFC 2132) options encoder/decoder class.

This is used with ryu.lib.packet.dhcp.dhcp.

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 corresponding args in this order.

Attribute Description
option_list ‘end option’ and ‘pad option’ are added automatically after the option class is stored in array.
options_len Option’s byte length. (‘magic cookie’, ‘end option’ and ‘pad option’ length including.)
magic_cookie The first four octets contain the decimal values 99, 130, 83 and 99.
class ryu.lib.packet.dhcp6.dhcp6(msg_type, options, transaction_id=None, hop_count=0, link_address='::', peer_address='::')

DHCPv6 (RFC 3315) header encoder/decoder class.

The serialized packet would looks like the ones described in the following sections.

  • RFC 3315 DHCP packet format

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 corresponding args in this order.

Attribute Description
msg_type Identifies the DHCP message type
transaction_id For unrelayed messages only: the transaction ID for this message exchange.
hop_count For relayed messages only: number of relay agents that have relayed this message.
link_address For relayed messages only: a global or site-local address that will be used by the server to identify the link on which the client is located.
peer_address For relayed messages only: the address of the client or relay agent from which the message to be relayed was received.
options Options carried in this message
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 three objects.

  • An object to describe the decoded header.
  • 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.
  • The rest of packet.
serialize(payload=None, prev=None)

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.dhcp6.options(option_list=None, options_len=0)

DHCP (RFC 3315) options encoder/decoder class.

This is used with ryu.lib.packet.dhcp6.dhcp6.

class ryu.lib.packet.dhcp6.option(code, data, length=0)

DHCP (RFC 3315) options encoder/decoder class.

This is used with ryu.lib.packet.dhcp6.dhcp6.options.

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 corresponding args in this order.

The format of DHCP options is:

0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | option-code | option-len | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | option-data | | (option-len octets) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Attribute Description
option-code An unsigned integer identifying the specific option type carried in this option.
option-len An unsigned integer giving the length of the option-data field in this option in octets.
option-data The data for the option; the format of this data depends on the definition of the option.
class ryu.lib.packet.igmp.igmp(msgtype=17, maxresp=0, csum=0, address='0.0.0.0')

Internet Group Management Protocol(IGMP, RFC 1112, RFC 2236) header encoder/decoder class.

http://www.ietf.org/rfc/rfc1112.txt

http://www.ietf.org/rfc/rfc2236.txt

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 corresponding args in this order.

Attribute Description
msgtype a message type for v2, or a combination of version and a message type for v1.
maxresp max response time in unit of 1/10 second. it is meaningful only in Query Message.
csum a check sum value. 0 means automatically-calculate when encoding.
address a group address value.
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 three objects.

  • An object to describe the decoded header.
  • 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.
  • The rest of packet.
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.igmp.igmpv3_query(msgtype=17, maxresp=100, csum=0, address='0.0.0.0', s_flg=0, qrv=2, qqic=0, num=0, srcs=None)

Internet Group Management Protocol(IGMP, RFC 3376) Membership Query message encoder/decoder class.

http://www.ietf.org/rfc/rfc3376.txt

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 corresponding args in this order.

Attribute Description
msgtype a message type for v3.
maxresp max response time in unit of 1/10 second.
csum a check sum value. 0 means automatically-calculate when encoding.
address a group address value.
s_flg when set to 1, routers suppress the timer process.
qrv robustness variable for a querier.
qqic an interval time for a querier in unit of seconds.
num a number of the multicast servers.
srcs a list of IPv4 addresses of the multicast servers.
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 three objects.

  • An object to describe the decoded header.
  • 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.
  • The rest of packet.
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.igmp.igmpv3_report(msgtype=34, csum=0, record_num=0, records=None)

Internet Group Management Protocol(IGMP, RFC 3376) Membership Report message encoder/decoder class.

http://www.ietf.org/rfc/rfc3376.txt

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 corresponding args in this order.

Attribute Description
msgtype a message type for v3.
csum a check sum value. 0 means automatically-calculate when encoding.
record_num a number of the group records.
records a list of ryu.lib.packet.igmp.igmpv3_report_group. None if no records.
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 three objects.

  • An object to describe the decoded header.
  • 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.
  • The rest of packet.
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.igmp.igmpv3_report_group(type_=0, aux_len=0, num=0, address='0.0.0.0', srcs=None, aux=None)

Internet Group Management Protocol(IGMP, RFC 3376) Membership Report Group Record message encoder/decoder class.

http://www.ietf.org/rfc/rfc3376.txt

This is used with ryu.lib.packet.igmp.igmpv3_report.

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 corresponding args in this order.

Attribute Description
type_ a group record type for v3.
aux_len the length of the auxiliary data.
num a number of the multicast servers.
address a group address value.
srcs a list of IPv4 addresses of the multicast servers.
aux the auxiliary data.