Reorganize examples into subdirectories

Examples directory has been growing, so add a bit of organization.

Signed-off-by: Brenden Blanco <[email protected]>

SPECS/bcc.spec

@@ -70,3 +70,5 @@ Python bindings for BPF Compiler Collection (BCC)
 %exclude /usr/share/bcc/examples/*.pyo
 %exclude /usr/share/bcc/examples/*/*.pyc
 %exclude /usr/share/bcc/examples/*/*.pyo
+%exclude /usr/share/bcc/examples/*/*/*.pyc
+%exclude /usr/share/bcc/examples/*/*/*.pyo

examples/CMakeLists.txt

@@ -1,5 +1,5 @@
-set(EXAMPLE_FILES hello_world.py task_switch.py task_switch.c simple_tc.py
- simulation.py vlan_learning.py vlan_learning.c)
-install(FILES ${EXAMPLE_FILES} DESTINATION share/bcc/examples)
+set(EXAMPLE_PROGRAMS hello_world.py)
+install(PROGRAMS ${EXAMPLE_PROGRAMS} DESTINATION share/bcc/examples)
 
-add_subdirectory(distributed_bridge)
+add_subdirectory(networking)
+add_subdirectory(tracing)

examples/networking/CMakeLists.txt

@@ -0,0 +1,8 @@
+set(EXAMPLE_FILES simulation.py)
+set(EXAMPLE_PROGRAMS simple_tc.py)
+install(FILES ${EXAMPLE_FILES} DESTINATION share/bcc/examples/networking)
+install(PROGRAMS ${EXAMPLE_PROGRAMS} DESTINATION share/bcc/examples/networking)
+
+add_subdirectory(distributed_bridge)
+add_subdirectory(neighbor_sharing)
+add_subdirectory(vlan_learning)

examples/networking/distributed_bridge/CMakeLists.txt

@@ -0,0 +1,4 @@
+set(EXAMPLE_FILES simulation.py tunnel.c tunnel_mesh.c)
+set(EXAMPLE_PROGRAMS main.py tunnel_mesh.py tunnel.py)
+install(FILES ${EXAMPLE_FILES} DESTINATION share/bcc/examples/networking/distributed_bridge)
+install(PROGRAMS ${EXAMPLE_PROGRAMS} DESTINATION share/bcc/examples/networking/distributed_bridge)

examples/networking/neighbor_sharing/CMakeLists.txt

@@ -0,0 +1,4 @@
+set(EXAMPLE_FILES README.txt simulation.py tc_neighbor_sharing.c)
+set(EXAMPLE_PROGRAMS tc_neighbor_sharing.py)
+install(FILES ${EXAMPLE_FILES} DESTINATION share/bcc/examples/networking/neighbor_sharing)
+install(PROGRAMS ${EXAMPLE_PROGRAMS} DESTINATION share/bcc/examples/networking/neighbor_sharing)

examples/networking/neighbor_sharing/README.txt

@@ -0,0 +1,57 @@
+This example shows how a combination of BPF programs can be used to perform
+per-IP classification and rate limiting. The simulation in this example
+shows an example where N+M devices are combined and use 1 WAN. Traffic sent
+from/to the "neighbor" devices have their combined bandwidth capped at
+128kbit, and the rest of the traffic can use an additional 1Mbit.
+
+This works by sharing a map between various tc ingress filters, each with
+a related set of bpf functions attached. The map stores a list of dynamically
+learned ip addresses that were seen on the neighbor devices and should be
+throttled.
+
+ /------------\ |
+neigh1 --|->->->->->->->-| | |
+neigh2 --|->->->->->->->-| <-128kb-| /------\ |
+neigh3 --|->->->->->->->-| | wan0 | wan | |
+ | ^ | br100 |-<-<-<--| sim | |
+ | clsfy_neigh() | | ^ \------/ |
+lan1 ----|->->->->->->->-| <--1Mb--| | |
+lan2 ----|->->->->->->->-| | classify_wan() |
+ ^ \------------/ |
+ pass() |
+
+To run the example:
+
+$ sudo /path/to/neighbor_sharing/neighbor_sharing.py
+Starting netserver with host 'IN(6)ADDR_ANY' port '12865' and family AF_UNSPEC
+Starting netserver with host 'IN(6)ADDR_ANY' port '12865' and family AF_UNSPEC
+Starting netserver with host 'IN(6)ADDR_ANY' port '12865' and family AF_UNSPEC
+Starting netserver with host 'IN(6)ADDR_ANY' port '12865' and family AF_UNSPEC
+Starting netserver with host 'IN(6)ADDR_ANY' port '12865' and family AF_UNSPEC
+Network ready. Create a shell in the wan0 namespace and test with netperf
+ (Neighbors are 172.16.1.100-102, and LAN clients are 172.16.1.150-151)
+ e.g.: ip netns exec wan0 netperf -H 172.16.1.100 -l 2
+Press enter when finished:
+
+
+In another shell:
+$ sudo ip netns exec wan0 netperf -H 172.16.1.100 -l 2
+MIGRATED TCP STREAM TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to 172.16.1.100 () port 0 AF_INET : demo
+Recv Send Send
+Socket Socket Message Elapsed
+Size Size Size Time Throughput
+bytes bytes bytes secs. 10^6bits/sec
+
+ 87380 16384 16384 4.30 0.18
+
+$ sudo ip netns exec wan0 netperf -H 172.16.1.150 -l 2
+MIGRATED TCP STREAM TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to 172.16.1.150 () port 0 AF_INET : demo
+Recv Send Send
+Socket Socket Message Elapsed
+Size Size Size Time Throughput
+bytes bytes bytes secs. 10^6bits/sec
+
+ 87380 16384 16384 4.10 1.01
+
+
+The bandwidth is throttled according to the IP.

examples/tc_neighbor_sharing.py → examples/networking/neighbor_sharing/tc_neighbor_sharing.py

@@ -2,29 +2,6 @@
 # Copyright (c) PLUMgrid, Inc.
 # Licensed under the Apache License, Version 2.0 (the "License")
 
-# This example shows how a combination of BPF programs can be used to perform
-# per-IP classification and rate limiting. The simulation in this example
-# shows an example where N+M devices are combined and use 1 WAN. Traffic sent
-# from/to the "neighbor" devices have their combined bandwidth capped at
-# 128kbit, and the rest of the traffic can use an additional 1Mbit.
-
-# This works by sharing a map between various tc ingress filters, each with
-# a related set of bpf functions attached. The map stores a list of dynamically
-# learned ip addresses that were seen on the neighbor devices and should be
-# throttled.
-
-# /------------\ |
-# neigh1 --|->->->->->->->-| | |
-# neigh2 --|->->->->->->->-| <-128kb-| /------\ |
-# neigh3 --|->->->->->->->-| | wan0 | wan | |
-# | ^ | br100 |-<-<-<--| sim | |
-# | clsfy_neigh() | | ^ \------/ |
-# lan1 ----|->->->->->->->-| <--1Mb--| | |
-# lan2 ----|->->->->->->->-| | classify_wan() |
-# ^ \------------/ |
-# pass() |
-
-
 from bcc import BPF
 from pyroute2 import IPRoute, NetNS, IPDB, NSPopen
 from simulation import Simulation

examples/simple_tc.py → examples/networking/simple_tc.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/python
 # Copyright (c) PLUMgrid, Inc.
 # Licensed under the Apache License, Version 2.0 (the "License")
 

examples/networking/tunnel_monitor/simulation.py

@@ -0,0 +1 @@
+../simulation.py

examples/networking/vlan_learning/CMakeLists.txt

@@ -0,0 +1,4 @@
+set(EXAMPLE_FILES README.txt simulation.py vlan_learning.c)
+set(EXAMPLE_PROGRAMS vlan_learning.py)
+install(FILES ${EXAMPLE_FILES} DESTINATION share/bcc/examples/networking/vlan_learning)
+install(PROGRAMS ${EXAMPLE_PROGRAMS} DESTINATION share/bcc/examples/networking/vlan_learning)

examples/networking/vlan_learning/README.txt

@@ -0,0 +1,43 @@
+This example shows a unique way to use a BPF program to demux any ethernet
+traffic into a pool of worker veth+namespaces (or any ifindex-based
+destination) depending on a configurable mapping of src-mac to ifindex. As
+part of the ingress processing, the program will dynamically learn the source
+ifindex of the matched source mac.
+
+Simulate a physical network with a vlan aware switch and clients that may
+connect to any vlan. The program will detect the known clients and pass the
+traffic through to a dedicated namespace for processing. Clients may have
+overlapping IP spaces and the traffic will still work.
+
+ | bpf program |
+cli0 --| | /--|-- worker0 |
+cli1 --| trunk | +->--->-handle_p2v(pkt)-> /---|-- worker1 |
+cli2 --|=======|=+ /----|-- worker2 |
+... --| | +-<---<-handle_v2p(pkt)-<-----|-- ... |
+cliN --| | \----|-- workerM |
+ | | ^ |
+ phys | veth |
+ switch | |
+
+To run the example, simply:
+
+sudo /path/to/vlan_learning/vlan_learning.py
+
+Serving HTTP on 0.0.0.0 port 80 ...
+Serving HTTP on 0.0.0.0 port 80 ...
+Serving HTTP on 0.0.0.0 port 80 ...
+ % Total % Received % Xferd Average Speed Time Time Time Current
+ Dload Upload Total Spent Left Speed
+ 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0172.16.1.100 - - [04/Nov/2015 10:54:47] "GET / HTTP/1.1" 200 -
+100 574 100 574 0 0 45580 0 --:--:-- --:--:-- --:--:-- 47833
+
+...
+
+Press enter to exit:
+mac 020000000000 rx pkts = 95, rx bytes = 7022
+ tx pkts = 0, tx bytes = 0
+mac 020000000001 rx pkts = 95, rx bytes = 7022
+ tx pkts = 0, tx bytes = 0
+mac 020000000002 rx pkts = 97, rx bytes = 7154
+ tx pkts = 0, tx bytes = 0
+

examples/networking/vlan_learning/simulation.py

@@ -0,0 +1 @@
+../simulation.py

examples/vlan_learning.py → examples/networking/vlan_learning/vlan_learning.py

@@ -2,27 +2,6 @@
 # Copyright (c) PLUMgrid, Inc.
 # Licensed under the Apache License, Version 2.0 (the "License")
 
-# This example shows a unique way to use a BPF program to demux any ethernet
-# traffic into a pool of worker veth+namespaces (or any ifindex-based
-# destination) depending on a configurable mapping of src-mac to ifindex. As
-# part of the ingress processing, the program will dynamically learn the source
-# ifindex of the matched source mac.
-
-# Simulate a physical network with a vlan aware switch and clients that may
-# connect to any vlan. The program will detect the known clients and pass the
-# traffic through to a dedicated namespace for processing. Clients may have
-# overlapping IP spaces and the traffic will still work.
-
-# | bpf program |
-# cli0 --| | /--|-- worker0 |
-# cli1 --| trunk | +->--->-handle_p2v(pkt)-> /---|-- worker1 |
-# cli2 --|=======|=+ /----|-- worker2 |
-# ... --| | +-<---<-handle_v2p(pkt)-<-----|-- ... |
-# cliN --| | \----|-- workerM |
-# | | ^ |
-# phys | veth |
-# switch | |
-
 from bcc import BPF
 from builtins import input
 from pyroute2 import IPRoute, NetNS, IPDB, NSPopen

examples/tracing/CMakeLists.txt

@@ -0,0 +1,6 @@
+set(EXAMPLE_FILES bitehist.c bitehist_example.txt disksnoop.c
+ disksnoop_example.txt task_switch.c tcpv4connect tcpv4connect_example.txt
+ vfsreadlat.c vfsreadlat_example.txt)
+set(EXAMPLE_PROGRAMS bitehist.py disksnoop.py task_switch.py trace_fields.py vfsreadlat.py)
+install(FILES ${EXAMPLE_FILES} DESTINATION share/bcc/examples/tracing)
+install(PROGRAMS ${EXAMPLE_PROGRAMS} DESTINATION share/bcc/examples/tracing)