Built In Modules and Ports

This text is auto-generated from comments in the module code. To edit the contents of this page, please edit the comments in bess/protobuf in the main BESS repository. To re-generate this page, check out and compile this repository, build and install, and then run the included generate_bess_module_docs.sh script in the bess/protobuf directory.

Top

module_msg.proto

ACL()

The module ACL creates an access control module which by default blocks all traffic, unless it contains a rule which specifies otherwise. Examples of ACL can be found in acl.bess

Input Gates: 1 Output Gates: 1

Field	Type	Label	Description
rules	ACL().Rule	repeated	A list of ACL rules.

ACL().Rule

One ACL rule is represented by the following 6-tuple.

Field	Type	Label	Description
src_ip	string	optional	Source IP block in CIDR. Wildcard if "".
dst_ip	string	optional	Destination IP block in CIDR. Wildcard if "".
src_port	uint32	optional	TCP/UDP source port. Wildcard if 0.
dst_port	uint32	optional	TCP/UDP Destination port. Wildcard if 0.
established	bool	optional	Not implemented
drop	bool	optional	Drop matched packets if true, forward if false. By default ACL drops all traffic.

ArpResponder()

The ARP Responder module is responding to ARP requests TODO: Dynamic learn new MAC's-IP's mapping

Input Gates: 1 Output Gates: 1

Field	Type	Label	Description
ip	string	optional	One ARP IP-MAC mapping
mac_addr	string	optional	The MAC address

BPF()

The BPF module is an access control module that sends packets out on a particular gate based on whether they match a BPF filter.

Input Gates: 1 Output Gates: many (configurable)

Field	Type	Label	Description
filters	BPF().Filter	repeated	The BPF initialized function takes a list of BPF filters.

BPF().Filter

One BPF filter is represented by the following 3-tuple.

Field	Type	Label	Description
priority	int64	optional	The priority level for this rule. If a packet matches multiple rules, it will be forwarded out the gate with the highest priority. If a packet matches multiple rules with the same priority, the behavior is undefined.
filter	string	optional	The actual BPF string.
gate	int64	optional	What gate to forward packets that match this BPF to.

BPF.Clear()

The BPF module has a command clear() that takes no parameters. This command removes all filters from the module.

Buffer()

The Buffer module takes no parameters to initialize (ie, Buffer() is sufficient to create one). Buffer accepts packets and stores them; it may forward them to the next module only after it has received enough packets to fill an entire PacketBatch.

Input Gates: 1 Output Gates: 1

Bypass()

The Bypass module forwards packets by emulating pre-defined packet processing overhead. It burns cpu cycles per_batch, per_packet, and per-bytes. Bypass is useful primarily for testing and performance evaluation.

Input Gates: 1 Output Gates: 1

Field	Type	Label	Description
cycles_per_batch	uint32	optional
cycles_per_packet	uint32	optional
cycles_per_byte	uint32	optional

DRR()

The Module DRR provides fair scheduling of flows based on a quantum which is number of bytes allocated to each flow on each round of going through all flows. Examples can be found [./bessctl/conf/samples/drr.bess]

Input_Gates: 1 Output_Gates: 1

Field	Type	Label	Description
num_flows	uint32	optional	Number of flows to handle in module
quantum	uint64	optional	the number of bytes to allocate to each on every round
max_flow_queue_size	uint32	optional	the max size that any Flows queue can get

DRRMaxFlowQueueSize()

The SetMaxQueueSize function sets a new maximum flow queue size for DRR module. If the flow's queue gets to this size, the module starts dropping packets to that flow until the queue is below this size.

Field	Type	Label	Description
max_queue_size	uint32	optional	the max size that any Flows queue can get

DRRQuantum()

the SetQuantumSize function sets a new quantum for DRR module to operate on.

Field	Type	Label	Description
quantum	uint32	optional	the number of bytes to allocate to each on every round

Dump()

The Dump module blindly forwards packets without modifying them. It periodically samples a packet and prints out out to the BESS log (by default stored in /tmp/bessd.INFO).

Input Gates: 1 Output Gates: 1

Field	Type	Label	Description
interval	double	optional	How frequently to sample and print a packet, in seconds.

Empty()

EtherEncap()

The EtherEncap module wraps packets in an Ethernet header, but it takes no parameters. Instead, Ethernet source, destination, and type are pulled from a packet's metadata attributes. For example: SetMetadata('dst_mac', 11:22:33:44:55) -> EtherEncap() This is useful when upstream modules wish to assign a MAC address to a packet, e.g., due to an ARP request.

Input Gates: 1 Output Gates: 1

ExactMatch()

The ExactMatch module splits packets along output gates according to exact match values in arbitrary packet fields. To instantiate an ExactMatch module, you must specify which fields in the packet to match over. You can add rules using the function ExactMatch.add(...) Fields may be stored either in the packet data or its metadata attributes. An example script using the ExactMatch code is found in bess/bessctl/conf/samples/exactmatch.bess.

Input Gates: 1 Output Gates: many (configurable)

Field	Type	Label	Description
fields	Field	repeated	A list of ExactMatch Fields
masks	FieldData	repeated	mask(i) corresponds to the mask for field(i)

ExactMatch.Add()

The ExactMatch module has a command add(...) that takes two parameters. The ExactMatch initializer specifies what fields in a packet to inspect; add() specifies which values to check for over these fields. add() inserts a new rule into the ExactMatch module such that traffic matching that bytestring will be forwarded out a specified gate. Example use: add(fields=[aton('12.3.4.5'), aton('5.4.3.2')], gate=2)

Field	Type	Label	Description
gate	uint64	optional	The gate to forward out packets that mach this rule.
fields	FieldData	repeated	The exact match values to check for

ExactMatch.Clear()

The ExactMatch module has a command clear() which takes no parameters. This command removes all rules from the ExactMatch module.

ExactMatch.Delete()

The ExactMatch module has a command delete(...) which deletes an existing rule. Example use: delete(fields=[aton('12.3.4.5'), aton('5.4.3.2')])

Field	Type	Label	Description
fields	FieldData	repeated	The field values for the rule to be deleted.

ExactMatch.SetDefaultGate()

The ExactMatch module has a command set_default_gate(...) which takes one parameter. This command routes all traffic which does not match a rule to a specified gate. Example use in bessctl: setDefaultGate(gate=2)

Field	Type	Label	Description
gate	uint64	optional	The gate number to send the default traffic out.

ExactMatchConfig

ExactMatchConfig represents the current runtime configuration of an ExactMatch module, as returned by get_runtime_config and set by set_runtime_config.

Field	Type	Label	Description
default_gate	uint64	optional
rules	ExactMatch.Add()	repeated

FlowGen()

The FlowGen module generates simulated TCP flows of packets with correct SYN/FIN flags and sequence numbers. This module is useful for testing, e.g., a NAT module or other flow-aware code. Packets are generated off a base, "template" packet by modifying the IP src/dst and TCP src/dst. By default, only the ports are changed and will be modified by incrementing the template ports by up to 20000 more than the template values.

Input Gates: 0 Output Gates: 1

Field	Type	Label	Description
template	bytes	optional	The packet "template". All data packets are derived from this template and contain the same payload.
pps	double	optional	The total number of packets per second to generate.
flow_rate	double	optional	The number of new flows to create every second. flow_rate must be <= pps.
flow_duration	double	optional	The lifetime of a flow in seconds.
arrival	string	optional	The packet arrival distribution -- must be either "uniform" or "exponential"
duration	string	optional	The flow duration distribution -- must be either "uniform" or "pareto"
quick_rampup	bool	optional	Whether or not to populate the flowgenerator with initial flows (start generating full pps rate immediately) or to wait for new flows to be generated naturally (all flows have a SYN packet).
ip_src_range	uint32	optional	When generating new flows, FlowGen modifies the template packet by changing the IP src, incrementing it by at most ip_src_range (e.g., if the base packet is 10.0.0.1 and range is 5, it will generate packets with IPs 10.0.0.1-10.0.0.6).
ip_dst_range	uint32	optional	When generating new flows, FlowGen modifies the template packet by changing the IP dst, incrementing it by at most ip_dst_range.
port_src_range	uint32	optional	When generating new flows, FlowGen modifies the template packet by changing the TCP port, incrementing it by at most port_src_range.
port_dst_range	uint32	optional	When generating new flows, FlowGen modifies the template packet by changing the TCP dst port, incrementing it by at most port_dst_range.

FlowGen.SetBurst()

The FlowGen module has a command set_burst(...) that allows you to specify the maximum number of packets to be stored in a single PacketBatch released by the module.

Field	Type	Label	Description
burst	uint64	optional

GenericDecap()

The GenericDecap module strips off the first few bytes of data from a packet.

Input Gates: 1 Ouptut Gates: 1

Field	Type	Label	Description
bytes	uint64	optional	The number of bytes to strip off.

GenericEncap()

The GenericEncap module adds a header to packets passing through it. Takes a list of fields. Each field is either:

1. {'size': X, 'value': Y} (for constant values)
2. {'size': X, 'attribute': Y} (for metadata attributes)

e.g.: GenericEncap([{'size': 4, 'value': 0xdeadbeef}, {'size': 2, 'attribute': 'foo'}, {'size': 2, 'value': 0x1234}]) will prepend a 8-byte header: de ad be ef <xx> <xx> 12 34 where the 2-byte <xx> <xx> comes from the value of metadata attribute 'foo' for each packet. An example script using GenericEncap is in bess/bessctl/conf/samples/generic_encap.bess.

Input Gates: 1 Output Gates: 1

Field	Type	Label	Description
fields	GenericEncap().EncapField	repeated

GenericEncap().EncapField

An EncapField represents one field in the new packet header.

Field	Type	Label	Description
size	uint64	optional	The length of the field.
attribute	string	optional	The metadata attribute name to pull the field value from
value	FieldData	optional	Or, the fixed value to insert into the packet.

HashLB()

The HashLB module partitions packets between output gates according to either a hash over their MAC src/dst (mode='l2'), their IP src/dst (mode='l3'), the full IP/TCP 5-tuple (mode='l4'), or the N-tuple defined by fields.

Input Gates: 1 Output Gates: many (configurable)

Field	Type	Label	Description
gates	int64	repeated	A list of gate numbers over which to partition packets
mode	string	optional	The mode ('l2', 'l3', or 'l4') for the hash function.
fields	Field	repeated	A list of fields that define a custom tuple.

HashLB.SetGates()

The HashLB module has a command set_gates(...) which takes one parameter. This function takes in a list of gate numbers to send hashed traffic out over. Example use in bessctl: lb.setGates(gates=[0,1,2,3])

Field	Type	Label	Description
gates	int64	repeated	A list of gate numbers to load balance traffic over

HashLB.SetMode()

The HashLB module has a command set_mode(...) which takes two parameters. The mode parameter specifies whether the load balancer will hash over the src/dest ethernet header ('l2'), over the src/dest IP addresses ('l3'), or over the flow 5-tuple ('l4'). Alternatively, if the fields parameter is set, the load balancer will hash over the N-tuple with the specified offsets and sizes. Example use in bessctl: lb.set_mode('l2')

Field	Type	Label	Description
mode	string	optional	What fields to hash over, 'l2', 'l3', and 'l4' are only valid values.
fields	Field	repeated	A list of fields that define a custom tuple.

IPEncap()

Encapsulates a packet with an IP header, where IP src, dst, and proto are filled in by metadata values carried with the packet. Metadata attributes must include: ip_src, ip_dst, ip_proto, ip_nexthop, and ether_type.

Input Gates: 1 Output Gates: 1

IPLookup()

An IPLookup module perfroms LPM lookups over a packet destination. IPLookup takes no parameters to instantiate. To add rules to the IPLookup table, use IPLookup.add()

Input Gates: 1 Output Gates: many (configurable, depending on rule values)

Field	Type	Label	Description
max_rules	uint32	optional	Maximum number of rules (default: 1024)
max_tbl8s	uint32	optional	Maximum number of IP prefixes with smaller than /24 (default: 128)

IPLookup.Add()

The IPLookup module has a command add(...) which takes three paramters. This function accepts the routing rules -- CIDR prefix, CIDR prefix length, and what gate to forward matching traffic out on. Example use in bessctl: table.add(prefix='10.0.0.0', prefix_len=8, gate=2)

Field	Type	Label	Description
prefix	string	optional	The CIDR IP part of the prefix to match
prefix_len	uint64	optional	The prefix length
gate	uint64	optional	The number of the gate to forward matching traffic on.

IPLookup.Clear()

The IPLookup module has a command clear() which takes no parameters. This function removes all rules in the IPLookup table. Example use in bessctl: myiplookuptable.clear()

IPLookup.Delete()

The IPLookup module has a command delete(...) which takes two paramters. This function accepts the routing rules -- CIDR prefix, CIDR prefix length, Example use in bessctl: table.delete(prefix='10.0.0.0', prefix_len=8)

Field	Type	Label	Description
prefix	string	optional	The CIDR IP part of the prefix to match
prefix_len	uint64	optional	The prefix length

L2Forward()

An L2Forward module forwards packets to an output gate according to exact-match rules over an Ethernet destination. Note that this is not a learning switch -- forwards according to fixed routes specified by add(..).

Input Gates: 1 Ouput Gates: many (configurable, depending on rules)

Field	Type	Label	Description
size	int64	optional	Configures the forwarding hash table -- total number of hash table entries.
bucket	int64	optional	Configures the forwarding hash table -- total number of slots per hash value.

L2Forward.Add()

The L2Forward module forwards traffic via exact match over the Ethernet destination address. The command add(...) allows you to specifiy a MAC address and which gate the L2Forward module should direct it out of.

Field	Type	Label	Description
entries	L2Forward.Add().Entry	repeated	A list of L2Forward entries.

L2Forward.Add().Entry

Field	Type	Label	Description
addr	string	optional	The MAC address to match
gate	int64	optional	Which gate to send out traffic matching this address.

L2Forward.Delete()

The L2Forward module has a function delete(...) to remove a rule from the MAC forwarding table.

Field	Type	Label	Description
addrs	string	repeated	The address to remove from the forwarding table

L2Forward.Lookup()

The L2Forward module has a function lookup(...) to query what output gate a given MAC address will be forwared to; it returns the gate ID number.

Field	Type	Label	Description
addrs	string	repeated	The MAC address to query for

L2Forward.LookupResponse

This message type provides the reponse to the L2Forward function lookup(..). It returns the gate that a requested MAC address is currently assigned to.

Field	Type	Label	Description
gates	uint64	repeated	The gate ID that the requested MAC address maps to

L2Forward.Populate()

The L2Forward module has a command populate(...) which allows for fast creation of the forwarding table given a range of MAC addresses. The function takes in a 'base' MAC address, a count (number of MAC addresses), and a gate_id. The module will route all MAC addresses starting from the base address, up to base+count address round-robin over gate_count total gates. For example, `populate(base='11:22:33:44:00', count = 10, gate_count = 2) would route addresses 11:22:33:44::(00, 02, 04, 06, 08) out a gate 0 and the odd-suffixed addresses out gate 1.

Field	Type	Label	Description
base	string	optional	The base MAC address
count	int64	optional	How many addresses beyond base to populate into the routing table
gate_count	int64	optional	How many gates to create in the L2Forward module.

L2Forward.SetDefaultGate()

For traffic reaching the L2Forward module which does not match a MAC rule, the function set_default_gate(...) allows you to specify a default gate to direct unmatched traffic to.

Field	Type	Label	Description
gate	int64	optional	The default gate to forward traffic which matches no entry to.

MACSwap()

The MACSwap module takes no arguments. It swaps the src/destination MAC addresses within a packet.

Input Gates: 1 Output Gates: 1

Measure()

The measure module tracks latencies, packets per second, and other statistics. It should be paired with a Timestamp module, which attaches a timestamp to packets. The measure module will log how long (in nanoseconds) it has been for each packet it received since it was timestamped. This module is somewhat experimental and undergoing various changes. There is a test for the the Measure module in bessctl/module_tests/timestamp.py.

Input Gates: 1 Output Gates: 1

Field	Type	Label	Description
offset	uint64	optional	Where to store the current time within the packet, offset in bytes.
jitter_sample_prob	double	optional	How often the module should sample packets for inter-packet arrival measurements (to measure jitter).
latency_ns_max	uint64	optional	maximum latency expected, in ns (default 0.1 s)
latency_ns_resolution	uint32	optional	resolution, in ns (default 100)

Measure.GetSummary()

The Measure module measures and collects latency/jitter data for packets annotated by a Timestamp module. Note that Timestamp and Measure module must reside on the server for accurate measurement (as a result, the most typical use case is measuring roundtrip time). Optionally, you can also retrieve percentile values by specifying points in "percentiles". For example, "percentiles" of [50.0, 99.0] will return [median, 99'th %-ile tail latency] in "percentile_values_ns" in the response.

Field	Type	Label	Description
clear	bool	optional	if true, the data will be all cleared after read
latency_percentiles	double	repeated	ascending list of real numbers in [0.0, 100.0]
jitter_percentiles	double	repeated	ascending list of real numbers in [0.0, 100.0]

Measure.GetSummaryResponse

The Measure module function get_summary() returns the following values. Note that the resolution value tells you how grainy the samples are, e.g., 100 means that anything from 0-99 ns counts as "0", anything from 100-199 counts as "100", and so on. The average is of samples using this graininess, but (being a result of division) may not be a multiple of the resolution.

Field	Type	Label	Description
timestamp	double	optional	Seconds since boot.
packets	uint64	optional	Total # of packets seen by this module.
bits	uint64	optional	Total # of bits seen by this module.
latency	Measure.GetSummaryResponse.Histogram	optional
jitter	Measure.GetSummaryResponse.Histogram	optional

Measure.GetSummaryResponse.Histogram

Field	Type	Label	Description
count	uint64	optional	Total # of measured data points, including above_range
above_range	uint64	optional	# of data points for the "too large value" bucket
resolution_ns	uint64	optional	resolution of measured data
min_ns	uint64	optional
avg_ns	uint64	optional
max_ns	uint64	optional
total_ns	uint64	optional
percentile_values_ns	uint64	repeated

Merge()

The merge module takes no parameters. It has multiple input gates, and passes out all packets from a single output gate.

Input Gates: many (configurable) Output Gates: 1

MetadataTest()

The MetadataTest module is used for internal testing purposes.

Field	Type	Label	Description
read	MetadataTest().ReadEntry	repeated
write	MetadataTest().WriteEntry	repeated
update	MetadataTest().UpdateEntry	repeated

MetadataTest().ReadEntry

Field	Type	Label	Description
key	string	optional
value	int64	optional

MetadataTest().UpdateEntry

Field	Type	Label	Description
key	string	optional
value	int64	optional

MetadataTest().WriteEntry

Field	Type	Label	Description
key	string	optional
value	int64	optional

MplsPop()

The MPLS pop module removes MPLS labels

Input Gates: 1 Output Gates: 2

Field	Type	Label	Description
remove_eth_header	bool	optional
next_eth_type	uint32	optional	The next ETH type to set

NAT()

The NAT module implements Dynamic IPv4 address/port translation, rewriting packet source addresses with external addresses as specified, and destination addresses for packets on the reverse direction. L3/L4 checksums are updated correspondingly. To see an example of NAT in use, see: bess/bessctl/conf/samples/nat.bess

Currently only supports TCP/UDP/ICMP. Note that address/port in packet payload (e.g., FTP) are NOT translated.

Input Gates: 2 (0 for internal->external, and 1 for external->internal direction) Output Gates: 2 (same as the input gate)

Field	Type	Label	Description
ext_addrs	NAT().ExternalAddress	repeated	list of external IP addresses

NAT().ExternalAddress

Field	Type	Label	Description
ext_addr	string	optional
port_ranges	NAT().PortRange	repeated

NAT().PortRange

Field	Type	Label	Description
begin	uint32	optional
end	uint32	optional
suspended	bool	optional

NoOp()

This module is used for testing purposes.

PortInc()

The PortInc module connects a physical or virtual port and releases packets from it. PortInc does not support multiqueueing. For details on how to configure PortInc using DPDK, virtual ports, or libpcap, see the sidebar in the wiki.

Input Gates: 0 Output Gates: 1

Field	Type	Label	Description
port	string	optional	The portname to connect to.
prefetch	bool	optional	Whether or not to prefetch packets from the port.

PortInc.SetBurst()

The module PortInc has a function set_burst(...) that allows you to specify the maximum number of packets to be stored in a single PacketBatch released by the module.

Field	Type	Label	Description
burst	uint64	optional	The maximum "burst" of packets (ie, the maximum batch size)

PortOut()

The PortOut module connects to a physical or virtual port and pushes packets to it. For details on how to configure PortOut with DPDK, virtual ports, libpcap, etc, see the sidebar in the wiki.

Input Gates: 1 Output Gates: 0

Field	Type	Label	Description
port	string	optional	The portname to connect to.

Queue()

The Queue module implements a simple packet queue.

Input Gates: 1 Output Gates: 1

Field	Type	Label	Description
size	uint64	optional	The maximum number of packets to store in the queue.
prefetch	bool	optional	When prefetch is enabled, the module will perform CPU prefetch on the first 64B of each packet onto CPU L1 cache. Default value is false.
backpressure	bool	optional

Queue.GetStatus()

Modules that are queues or contain queues may contain functions get_status() that return Queue.GetStatusResponse.

Queue.GetStatusResponse

Modules that are queues or contain queues may contain functions get_status() that take no parameters and returns the queue occupancy and size.

Field	Type	Label	Description
count	uint64	optional	The number of packets currently in the queue.
size	uint64	optional	The maximum number of packets the queue can contain.
enqueued	uint64	optional	total enqueued
dequeued	uint64	optional	total dequeued
dropped	uint64	optional	total dropped

Queue.SetBurst()

The module Queue has a function set_burst(...) that allows you to specify the maximum number of packets to be stored in a single PacketBatch released by the module.

Field	Type	Label	Description
burst	uint64	optional	The maximum "burst" of packets (ie, the maximum batch size)

Queue.SetSize()

The module Queue has a function set_size(...) that allows specifying the size of the queue in total number of packets.

Field	Type	Label	Description
size	uint64	optional	The maximum number of packets to store in the queue.

QueueInc()

The module QueueInc produces input packets from a physical or virtual port. Unlike PortInc, it supports multiqueue ports. For details on how to configure QueueInc with DPDK, virtualports, libpcap, etc, see the sidebar in the wiki.

Input Gates: 0 Output Gates: 1

Field	Type	Label	Description
port	string	optional	The portname to connect to (read from).
qid	uint64	optional	The queue on that port to read from. qid starts from 0.
prefetch	bool	optional	When prefetch is enabled, the module will perform CPU prefetch on the first 64B of each packet onto CPU L1 cache. Default value is false.

QueueInc.SetBurst()

The module QueueInc has a function set_burst(...) that allows you to specify the maximum number of packets to be stored in a single PacketBatch released by the module.

Field	Type	Label	Description
burst	uint64	optional	The maximum "burst" of packets (ie, the maximum batch size)

QueueOut()

The QueueOut module releases packets to a physical or virtual port. Unlike PortOut, it supports multiqueue ports. For details on how to configure QueueOut with DPDK, virtualports, libpcap, etc, see the sidebar in the wiki.

Input Gates: 1 Output Gates: 0

Field	Type	Label	Description
port	string	optional	The portname to connect to.
qid	uint64	optional	The queue on that port to write out to.

RandomSplit()

The RandomSplit module randomly split/drop packets

InputGates: 1 Output Gates: many (configurable)

Field	Type	Label	Description
drop_rate	double	optional	Probability of dropping packet.
gates	int64	repeated	A list of gate numbers to split the traffic.

RandomSplit.SetDroprate()

The RandomSplit module has a function set_droprate(...) which specifies the probability of dropping packets

Field	Type	Label	Description
drop_rate	double	optional	Probability of dropping packet.

RandomSplit.SetGates()

The RandomSplit module has a function set_gates(...) which changes the total number of output gates in the module.

Field	Type	Label	Description
gates	int64	repeated	A list of gate numbers to split the traffic.

RandomUpdate()

The RandomUpdate module rewrites a specified field (offset and size) in a packet with a random value between a specified min and max values.

Input Gates: 1 Output Gates: 1

Field	Type	Label	Description
fields	RandomUpdate().Field	repeated	A list of Random Update Fields.

RandomUpdate().Field

RandomUpdate's Field specifies where to rewrite, and what values to rewrite in each packet processed.

Field	Type	Label	Description
offset	int64	optional	Offset in bytes of where to rewrite.
size	uint64	optional	The number of bytes to write.
min	uint64	optional	The minimum value to insert into the packet.
max	uint64	optional	The maximum value to insert into the packet.

RandomUpdate.Clear()

The function clear() for RandomUpdate takes no parameters and clears all state in the module.

Replicate()

The Replicate module makes copies of a packet sending one copy out over each of n output gates.

Input Gates: 1 Output Gates: many (configurable)

Field	Type	Label	Description
gates	int64	repeated	A list of gate numbers to send packet copies to.

Replicate.SetGates()

The Replicate module has a function set_gates(...) which changes the total number of output gates in the module.

Field	Type	Label	Description
gates	int64	repeated	A list of gate numbers to replicate the traffic over.

Rewrite()

The Rewrite module replaces an entire packet body with a packet "template" converting all packets that pass through to copies of the of one of the templates.

Input Gates: 1 Output Gates: 1

Field	Type	Label	Description
templates	bytes	repeated	A list of bytestrings representing packet templates.

Rewrite.Clear()

The function clear() for Rewrite takes no parameters and clears all state in the module.

RoundRobin()

The RoundRobin module splits packets from one input gate across multiple output gates.

Input Gates: 1 Output Gates: many (configurable)

Field	Type	Label	Description
gates	int64	repeated	A list of gate numbers to split packets across.
mode	string	optional	Whether to split across gate with every 'packet' or every 'batch'.

RoundRobin.SetGates()

The RoundRobin module has a function set_gates(...) which changes the total number of output gates in the module.

Field	Type	Label	Description
gates	int64	repeated	A list of gate numbers to round-robin the traffic over.

RoundRobin.SetMode()

The RoundRobin module has a function set_mode(...) which specifies whether to balance traffic across gates per-packet or per-batch.

Field	Type	Label	Description
mode	string	optional	whether to perform 'packet' or 'batch' round robin partitioning.

SetMetadata()

The SetMetadata module adds metadata attributes to packets, which are not stored or sent out with packet data. For examples of SetMetadata use, see bess/bessctl/conf/attr_match.bess

Input Gates: 1 Output Gates: 1

Field	Type	Label	Description
attrs	SetMetadata().Attribute	repeated	A list of attributes to attach to the packet.

SetMetadata().Attribute

SetMetadata Attribute describes a metadata attribute and value to attach to every packet. If copying data from a packet buffer, SetMetadata can also logically shift then mask the value before storing it as metadata, i.e., metadata_value = (packet_value >> rshift_bits) & mask.

Field	Type	Label	Description
name	string	optional	The metadata attribute name.
size	uint64	optional	The size of values stored in this attribute in bytes.
value_int	uint64	optional	An integer value to store in the packet (host-order).
value_bin	bytes	optional	A binary value to store in the packet (host-order).
offset	int32	optional	An index in the packet data to store copy into the metadata attribute.
mask	bytes	optional	An array of bit masks to apply to each of the bytes copied starting from offset. If empty, the mask [0xFF,....,0xFF] will be used.
rshift_bits	int32	optional	The number of bits to shift the value at offset by before masking. Must be a multiple of 8. Positive and negative values represent right and left shifts respectively.

Sink()

The sink module drops all packets that are sent to it.

Input Gates: 1 Output Gates: 0

Source()

The Source module generates packets with no payload contents.

Input Gates: 0 Output Gates: 1

Field	Type	Label	Description
pkt_size	uint64	optional	The size (in bytes) of packet data to produce.

Source.SetBurst()

The Source module has a function set_burst(...) which specifies the maximum number of packets to release in a single packetbatch from the module.

Field	Type	Label	Description
burst	uint64	optional	The maximum number of packets to release in a packetbatch from the module.

Source.SetPktSize()

The Source module has a function set_pkt_size(...) which specifies the size of packets to be produced by the Source module.

Field	Type	Label	Description
pkt_size	uint64	optional	The size (in bytes) of the packets for Source to create.

Split()

The Split module is a basic classifier which directs packets out a gate based on data in the packet (e.g., if the read in value is 3, the packet is directed out output gate 3).

Input Gates: 1 Output Gates: many (up to 2^(size * 8))

Field	Type	Label	Description
size	uint64	optional	The size of the value to read in bytes
attribute	string	optional	The name of the metadata field to read.
offset	int64	optional	The offset (in bytes) of the data field to read.

StaticNAT()

Static NAT module implements one-to-one translation of source/destination IPv4 addresses. No port number is translated. L3/L4 checksums are updated correspondingly. To see an example of NAT in use, see: bess/bessctl/conf/samples/nat.bess

Forward direction (from input gate 0 to output gate 0):

• Source IP address is updated, from internal to external address. Reverse direction (from input gate 1 to output gate 1):
• Destination IP address is updated, from external to internal address. If the original address is outside any of the ranges, packets are forwarded without NAT.

Note that address in packet payload (e.g., FTP) are NOT translated.

Input Gates: 2 (0 for internal->external, and 1 for external->internal direction) Output Gates: 2 (same as the input gate)

Field	Type	Label	Description
pairs	StaticNAT().AddressRangePair	repeated

StaticNAT().AddressRange

Field	Type	Label	Description
start	string	optional	first IP address to use
end	string	optional	last IP address to use

StaticNAT().AddressRangePair

Field	Type	Label	Description
int_range	StaticNAT().AddressRange	optional
ext_range	StaticNAT().AddressRange	optional	should be the same size as int_range

Timestamp()

The timestamp module takes an offset parameter. It inserts the current time in nanoseconds into the packet, to be used for latency measurements alongside the Measure module. The default offset is after an IPv4 UDP header.

Input Gates: 1 Output Gates: 1

Field	Type	Label	Description
offset	uint64	optional

Update()

The Update module rewrites a field in a packet's data with a specific value.

Input Gates: 1 Output Gates: 1

Field	Type	Label	Description
fields	Update().Field	repeated	A list of Update Fields.

Update().Field

Update Field describes where in a packet's data to rewrite, and with what value.

Field	Type	Label	Description
offset	int64	optional	The offset in the packet in bytes to rewrite at.
size	uint64	optional	The number of bytes to rewrite (max 8 bytes).
value	uint64	optional	The value to write into the packet, max 8 bytes.

Update.Clear()

The function clear() for Update takes no parameters and clears all state in the module.

UrlFilter()

The URLFilter performs TCP reconstruction over a flow and blocks connections which mention a banned URL.

Input Gates: 2 Output Gates: 2

Note that the add() command takes this same argument, and the clear() command takes an empty argument.

Field	Type	Label	Description
blacklist	UrlFilter().Url	repeated	A list of Urls to block.

UrlFilter().Url

A URL consists of a host and a path.

Field	Type	Label	Description
host	string	optional	Host field, e.g. "www.google.com"
path	string	optional	Path prefix, e.g. "/"

UrlFilterConfig

The runtime configuration of a URLFilter is the current blacklist. This means that getting the () gets an empty list: we assume anyone using get_initial_arg is also using get_runtime_config.

Field	Type	Label	Description
blacklist	UrlFilter().Url	repeated

VLANPop()

VLANPop removes the VLAN tag.

Input Gates: 1 Output Gates: 1

VLANPush()

VLANPush appends a VLAN tag with a specified TCI value.

Input Gates: 1 Output Gates: 1

Field	Type	Label	Description
tci	uint64	optional	The TCI value to insert in the VLAN tag.

VLANSplit()

Splits packets across output gates according to VLAN id (e.g., id 3 goes out gate 3).

Input Gates: 1 Output Gates: many

VXLANDecap()

VXLANDecap module decapsulates a VXLAN header on a packet.

Input Gates: 1 Output Gates: 1

VXLANEncap()

VXLANEncap module wraps a packet in a VXLAN header with a specified destination port.

Input Gates: 1 Output Gates: 1

Field	Type	Label	Description
dstport	uint64	optional	The destination UDP port

WildcardMatch()

The WildcardMatch module matches over multiple fields in a packet and pushes packets that do match out a specified gate, and those that don't out a default gate. WildcardMatch is initialized with the fields it should inspect over, rules are added via the add(...) function. An example of WildcardMatch is in bess/bessctl/conf/samples/wildcardmatch.bess

Input Gates: 1 Output Gates: many (configurable)

Field	Type	Label	Description
fields	Field	repeated	A list of WildcardMatch fields.

WildcardMatch.Add()

The module WildcardMatch has a command add(...) which inserts a new rule into the WildcardMatch module. For an example of code using WilcardMatch see bess/bessctl/conf/samples/wildcardmatch.bess.

Field	Type	Label	Description
gate	uint64	optional	Traffic matching this new rule will be sent to this gate.
priority	int64	optional	If a packet matches multiple rules, the rule with higher priority will be applied. If priorities are equal behavior is undefined.
values	FieldData	repeated	The values to check for in each field.
masks	FieldData	repeated	The bitmask for each field -- set 0x0 to ignore the field altogether.

WildcardMatch.Clear()

The function clear() for WildcardMatch takes no parameters, it clears all state in the WildcardMatch module (is equivalent to calling delete for all rules)

WildcardMatch.Delete()

The module WildcardMatch has a command delete(...) which removes a rule -- simply specify the values and masks from the previously inserted rule to remove them.

Field	Type	Label	Description
values	FieldData	repeated	The values being checked for in the rule
masks	FieldData	repeated	The bitmask from the rule.

WildcardMatch.SetDefaultGate()

For traffic which does not match any rule in the WildcardMatch module, the set_default_gate(...) function specifies which gate to send this extra traffic to.

Field	Type	Label	Description
gate	uint64	optional

WildcardMatchConfig

WildcardMatchConfig represents the current runtime configuration of a WildcardMatch module, as returned by get_runtime_config and set by set_runtime_config.

Field	Type	Label	Description
default_gate	uint64	optional
rules	WildcardMatch.Add()	repeated

WorkerSplit()

WorkerSplit splits packets based on the worker calling ProcessBatch(). It has two modes.

1. Packets from worker x are mapped to output gate x. This is the default mode.
2. When the worker_gates field is set, packets from a worker x are mapped to worker_gates[x]. In this mode, packet batches from workers not mapped to an output gate will be dropped.

Calling the reset command with an empty worker_gates field will revert WorkerSplit to the default mode.

Input Gates: 1 Output Gates: many

Field	Type	Label	Description
worker_gates	WorkerSplit().WorkerGatesEntry	repeated

WorkerSplit().WorkerGatesEntry

Field	Type	Label	Description
key	uint32	optional
value	uint32	optional

Scalar Value Types

.proto Type	Notes	C++ Type	Java Type	Python Type
double		double	double	float
float		float	float	float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long
uint32	Uses variable-length encoding.	uint32	int	int/long
uint64	Uses variable-length encoding.	uint64	long	int/long
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long
sfixed32	Always four bytes.	int32	int	int
sfixed64	Always eight bytes.	int64	long	int/long
bool		bool	boolean	boolean
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str