Writing a BESS Configuration Script

Once you know how to use bessctl, you know how to interact with BESS. So far, you've configured BESS by telling it to load some built-in BESS sample scripts. This page will tell you how to write your own configuration scripts.

Looking Inside a Script

First let's look at a familiar configuration script: samples/acl. From the bess/ main directory, the file is stored in bess/bessctl/conf/samples/acl.bess; go ahead and open it in your editor of choice (which we presume is vim if you are a cool person).

Here's what you will see: import scapy.all as scapy import socket

def aton(ip):
     return socket.inet_aton(ip)

# Craft a packet with the specified IP addresses
def gen_packet(proto, src_ip, dst_ip):
    eth = scapy.Ether(src='02:1e:67:9f:4d:ae', dst='06:16:3e:1b:72:32')
    ip = scapy.IP(src=src_ip, dst=dst_ip)
    udp = proto(sport=10001, dport=10002)
    payload = 'helloworld'
    pkt = eth/ip/udp/payload
    return str(pkt)

packets = [gen_packet(scapy.UDP, '172.16.100.1', '10.0.0.1'),
           gen_packet(scapy.UDP, '172.12.55.99', '12.34.56.78'),
           gen_packet(scapy.UDP, '172.12.55.99', '10.0.0.1'),
           gen_packet(scapy.UDP, '172.16.100.1', '12.34.56.78'),
           gen_packet(scapy.TCP, '172.12.55.99', '12.34.56.78'),
           gen_packet(scapy.UDP, '192.168.1.123', '12.34.56.78'),
          ]

fw::ACL(rules=[{'src_ip': '172.12.0.0/16', 'drop': False}])

Source() -> Rewrite(templates=packets) -> fw -> Sink()

At first glance, a couple of things should become clear to you:

• BESS scripts are really just Python programs with a few additional features glued in.
  • You can see how these additional features are glued in in bess/bessctl/sugar.py if you are super curious.
  • The key "sugar" features to know about: you can create modules by declaring module objects, you can connect modules to each other (connect their gates) using arrows -> (which represent unidirectional packet flow) and you can give a module a name by assigning a name with :: (like fw::ACL(... in the example above).
• You can create packets in your script using scapy, which is a convenient packet-manipulation library in Python.
• You can write functions, create lists, etc. all like in normal Python.

What is happening under the hood when I run a script?