Built In Modules and Ports

Built-In Modules and Ports

The module_msg.proto file is stored in bess/protobuf/ and it supplies the glue between bessd modules and bessctl modules. Whenever you call a function in bessctl, a corresponding function is called on modules in bessd. This file lists all modules, their initialization parameters and any functions that may be called on them. The communication between bessctl and bessd is handled by grpc and protobuf.

Table of Contents

• module_msg.proto
• ACL()
• ACL().Rule
• BPF()
• BPF().Filter
• BPF.Clear()
• Buffer()
• Bypass()
• Dump()
• EtherEncap()
• ExactMatch()
• ExactMatch().Field
• ExactMatch.Add()
• ExactMatch.Clear()
• ExactMatch.Delete()
• ExactMatch.SetDefaultGate()
• FlowGen()
• GenericDecap()
• GenericEncap()
• GenericEncap().Field
• HashLB()
• HashLB.SetGates()
• HashLB.SetMode()
• IPEncap()
• IPLookup()
• IPLookup.Add()
• IPLookup.Clear()
• L2Forward()
• L2Forward.Add()
• L2Forward.Add().Entry
• L2Forward.Delete()
• L2Forward.Lookup()
• L2Forward.LookupResponse
• L2Forward.Populate()
• L2Forward.SetDefaultGate()
• MACSwap()
• Measure()
• Measure.GetSummary()
• Measure.GetSummaryResponse
• Merge()
• MetadataTest()
• MetadataTest().ReadEntry
• MetadataTest().UpdateEntry
• MetadataTest().WriteEntry
• NAT()
• NAT().Rule
• NoOp()
• PortInc()
• PortInc.SetBurst()
• PortOut()
• Queue()
• Queue.SetBurst()
• Queue.SetSize()
• QueueInc()
• QueueInc.SetBurst()
• QueueOut()
• RandomUpdate()
• RandomUpdate().Field
• RandomUpdate.Clear()
• Rewrite()
• Rewrite.Clear()
• RoundRobin()
• RoundRobin.SetGates()
• RoundRobin.SetMode()
• SetMetadata()
• SetMetadata().Attribute
• Sink()
• Source()
• Source.SetBurst()
• Source.SetPktSize()
• Split()
• Timestamp()
• Update()
• Update().Field
• Update.Clear()
• UrlFilter()
• UrlFilter().Url
• VLANPop()
• VLANPush()
• VLANSplit()
• VXLANDecap()
• VXLANEncap()
• WildcardMatch()
• WildcardMatch().Field
• WildcardMatch.Add()
• WildcardMatch.Clear()
• WildcardMatch.Delete()
• WildcardMatch.SetDefaultGate()
• Scalar Value Types

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](https://github.com/NetSys/bess/blob/master/bessctl/conf/samples/acl.bess)

Field	Type	Label	Description
rules	ACL().Rule	repeated

### ACL().Rule

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	Source port: 80. Wildcard if 0.
dst_port	uint32	optional	Destination port. Wildcard if 0.
established	bool	optional	Not implemented
drop	bool	optional	Drop matched packets if true.

### BPF()

Field	Type	Label	Description
filters	BPF().Filter	repeated

### BPF().Filter

Field	Type	Label	Description
priority	int64	optional
filter	string	optional
gate	int64	optional

### BPF.Clear() The BPF module has a command `clear()` that takes no parameters. Example in bessctl: filter::BPF("src port 80") filter.clear() This command removes all filters from the module.

Field	Type	Label	Description

### Buffer()

Field	Type	Label	Description

### Bypass()

Field	Type	Label	Description

### Dump()

Field	Type	Label	Description
interval	double	optional

### EtherEncap()

Field	Type	Label	Description

### ExactMatch()

Field	Type	Label	Description
fields	ExactMatch().Field	repeated

### ExactMatch().Field

Field	Type	Label	Description
size	uint64	optional
mask	uint64	optional
name	string	optional
offset	int64	optional

### 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 i 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	bytes	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.

Field	Type	Label	Description

### 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	bytes	repeated	The field values for the rule to be deleted.

### ExactMatch.SetDefaultGate() The ExactMatch module has a command `setDefaultGate(...)` 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.

### FlowGen()

Field	Type	Label	Description
template	bytes	optional
pps	double	optional
flow_rate	double	optional
flow_duration	double	optional
arrival	string	optional
duration	string	optional
quick_rampup	bool	optional
ip_src_range	uint32	optional
ip_dst_range	uint32	optional
port_src_range	uint32	optional
port_dst_range	uint32	optional

### GenericDecap()

Field	Type	Label	Description
bytes	uint64	optional

### GenericEncap()

Field	Type	Label	Description
fields	GenericEncap().Field	repeated

### GenericEncap().Field

Field	Type	Label	Description
size	uint64	optional
attr_name	string	optional
value	uint64	optional

### HashLB()

Field	Type	Label	Description
gates	int64	repeated
mode	string	optional

### HashLB.SetGates() The HashLB module has a command `setGates(...)` 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 `setMode(...)` which takes one parameter. The mode 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). Example use in bessctl: `lb.setMode('l2')`

Field	Type	Label	Description
mode	string	optional	What fields to hash over, l1, l2, or l3 are only valid values.

### IPEncap()

Field	Type	Label	Description

### IPLookup()

Field	Type	Label	Description

### 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()`

Field	Type	Label	Description

### L2Forward()

Field	Type	Label	Description
size	int64	optional
bucket	int64	optional

### 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

### 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 funciton 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 `setDefaultGate(...)` allows you to specify a default gate to direct unmatched traffic to.

Field	Type	Label	Description
gate	int64	optional

### MACSwap()

Field	Type	Label	Description

### Measure()

Field	Type	Label	Description
warmup	int64	optional

### Measure.GetSummary() This function requests a summary of the statistics stored in the Measure module. It takes no parameters and returns a GetSummaryResponse.

Field	Type	Label	Description

### Measure.GetSummaryResponse The Measure module function `getSummary()` takes no parameters and returns the following values.

Field	Type	Label	Description
timestamp	double	optional	What time it is now?
packets	uint64	optional	The total number of packets seen by this module.
bits	uint64	optional	The total number of bits seen by this module.
total_latency_ns	uint64	optional	Sum of all round trip times across all packets
latency_min_ns	uint64	optional	The minimum latency for any packet observed by the Measure module.
latency_avg_ns	uint64	optional	The average latency for all packets.
latency_max_ns	uint64	optional	The max latency for any packet
latency_50_ns	uint64	optional	The 50th percentile latency over all packets
latency_99_ns	uint64	optional	The 99th percentile latency over all packets.

### Merge()

Field	Type	Label	Description

### MetadataTest()

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

### NAT()

Field	Type	Label	Description
rules	NAT().Rule	repeated

### NAT().Rule

Field	Type	Label	Description
internal_addr_block	string	optional	Internal IP block in CIDR.
external_addr_block	string	optional	External IP block in CIDR.

### NoOp()

Field	Type	Label	Description

### PortInc()

Field	Type	Label	Description
port	string	optional
burst	int64	optional
prefetch	bool	optional

### PortInc.SetBurst() The module PortInc has a function SetBurst 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	int64	optional	The maximum "burst" of packets (ie, the maximum batch size)

### PortOut()

Field	Type	Label	Description
port	string	optional

### Queue()

Field	Type	Label	Description
size	uint64	optional
burst	int64	optional
prefetch	bool	optional

### Queue.SetBurst() The module QueueInc has a function `setBurst(...)` 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	int64	optional	The maximum "burst" of packets (ie, the maximum batch size)

### Queue.SetSize() The module QueueInc has a function `setSize(...)` 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()

Field	Type	Label	Description
port	string	optional
qid	uint64	optional
burst	int64	optional
prefetch	bool	optional

### QueueInc.SetBurst() The module QueueInc has a function `setBurst(...)` 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	int64	optional	The maximum "burst" of packets (ie, the maximum batch size)

### QueueOut()

Field	Type	Label	Description
port	string	optional
qid	uint64	optional

### RandomUpdate()

Field	Type	Label	Description
fields	RandomUpdate().Field	repeated

### RandomUpdate().Field

Field	Type	Label	Description
offset	int64	optional
size	uint64	optional
min	uint64	optional
max	uint64	optional

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

Field	Type	Label	Description

### Rewrite()

Field	Type	Label	Description
templates	bytes	repeated

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

Field	Type	Label	Description

### RoundRobin()

Field	Type	Label	Description
gates	int64	repeated
mode	string	optional

### RoundRobin.SetGates()

Field	Type	Label	Description
gates	int64	repeated

### RoundRobin.SetMode()

Field	Type	Label	Description
mode	string	optional

### SetMetadata()

Field	Type	Label	Description
attrs	SetMetadata().Attribute	repeated

### SetMetadata().Attribute

Field	Type	Label	Description
name	string	optional
size	uint64	optional
value_int	uint64	optional
value_bin	bytes	optional
offset	int64	optional

### Sink()

Field	Type	Label	Description

### Source()

Field	Type	Label	Description
pkt_size	uint64	optional
burst	uint64	optional

### Source.SetBurst()

Field	Type	Label	Description
burst	uint64	optional

### Source.SetPktSize()

Field	Type	Label	Description
pkt_size	uint64	optional

### Split()

Field	Type	Label	Description
size	uint64	optional
name	string	optional
offset	int64	optional

### Timestamp()

Field	Type	Label	Description

### Update()

Field	Type	Label	Description
fields	Update().Field	repeated

### Update().Field

Field	Type	Label	Description
offset	int64	optional
size	uint64	optional
value	uint64	optional

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

Field	Type	Label	Description

### UrlFilter()

Field	Type	Label	Description
blacklist	UrlFilter().Url	repeated

### UrlFilter().Url

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

### VLANPop()

Field	Type	Label	Description

### VLANPush()

Field	Type	Label	Description
tci	uint64	optional

### VLANSplit()

Field	Type	Label	Description

### VXLANDecap()

Field	Type	Label	Description

### VXLANEncap()

Field	Type	Label	Description
dstport	uint64	optional

### WildcardMatch()

Field	Type	Label	Description
fields	WildcardMatch().Field	repeated

### WildcardMatch().Field

Field	Type	Label	Description
size	uint64	optional
offset	uint64	optional
attribute	string	optional

### 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	The gate to direct traffic matching this rule to.
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	uint64	repeated	The values to check for in each fieild.
masks	uint64	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)

Field	Type	Label	Description

### 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	uint64	repeated	The values being checked for in the rule
masks	uint64	repeated	The bitmask from the rule.

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

Field	Type	Label	Description
gate	uint64	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