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.
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:
- {'size': X, 'value': Y} (for constant values)
- {'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
where the 2-byte '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.
- Packets from worker
xare mapped to output gatex. This is the default
mode. - When the
worker_gatesfield is set, packets from a workerxare mapped
toworker_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 |